Give a finger a meaning beyond "it was you"

The trustlet has always reported WHICH finger matched and the daemon only ever
used it to answer yes. A table in /etc/fingerprintd/actions.conf now gives each
finger a meaning: run a command as root, tell the user's session, or report
no-match while doing one of those anyway -- which is duress, where the phone
should look like it simply did not recognise the finger.

Two rules shaped the design.

Root does not launch applications. The daemon has no session bus, no display
and no user environment, so a `session` rule carries no command at all: the
daemon emits net.catcrafts.Fingerprintd1.FingerMatched(finger, uid) and an
agent in the user's own session decides what that means from the user's own
configuration. The only commands in the file are ones root is meant to run.

Which makes the file a root shell, and the parser treats it as one. It is
refused outright unless root owns it and nobody else can write it, group
included. A malformed line rejects the WHOLE file rather than being skipped:
applying the prefix would leave a policy nobody wrote, and the missing half
could be the one that mattered. That property is tested, and the test caught it
being false the first time -- rules accumulated before the bad line survived
the rejection.

A system command must be an absolute path, because resolving a bare name
through PATH makes what root runs depend on an environment this daemon does not
control. It is double-forked with a scrubbed environment so an action may
outlive the daemon (a reboot) without ever stalling the worker thread that is
the only thread allowed to touch the trustlet.

Ordering is deliberate: the verdict override happens before the client is told,
because that is the point of duress; the session signal and the root command
happen after, on the same principle that keeps the harvest and the save off the
unlock path.

No actions.conf ships. An example goes to /usr/share/doc, because shipping a
root shell nobody asked for is not a default.

Not yet exercised on hardware.

packaging/APKBUILD

@@ -10,7 +10,7 @@
 # Alpine, so an APKBUILD that compiled from source could not be built by
 # anyone but us either.
 pkgname=fingerprintd
-pkgver=0.1.3
+pkgver=0.2.0
 pkgrel=0
 pkgdesc="Fingerprint daemon for the Fairphone 6 (FocalTech FT9391 behind QTEE)"
 url="https://forgejo.catcrafts.net/Catcrafts/fingerprintd"
@@ -101,6 +101,17 @@ package() {
 	# same mechanism soc-fairphone-fp6-audio uses for the amp config.
 	install -Dm644 20-focal64.manifest \
 		"$pkgdir"/usr/share/fp6-vendor-blobs/manifest.d/20-focal64.manifest
+
+	# The PAM service kscreenlocker substacks and Alpine does not provide.
+	# Vendor directory, so /etc/pam.d still overrides it.
+	install -Dm644 fingerprint-auth.pam \
+		"$pkgdir"/usr/lib/pam.d/fingerprint-auth
+
+	# Documentation, not configuration: shipping an /etc/fingerprintd/
+	# actions.conf would be shipping a root shell nobody asked for. The
+	# feature is off until an administrator installs one.
+	install -Dm644 actions.conf.example \
+		"$pkgdir"/usr/share/doc/$pkgname/actions.conf.example
 }
 
 systemd() {

packaging/actions.conf.example

@@ -0,0 +1,61 @@
+# fingerprintd — per-finger actions.
+#
+# Install as /etc/fingerprintd/actions.conf. With no such file, a finger does
+# exactly what it always did: it unlocks, and nothing else happens.
+#
+# THIS FILE IS A ROOT SHELL. Every `system` line is a command root runs when
+# that finger touches the sensor, so anything able to write this file owns the
+# machine at the next press. fingerprintd refuses the whole file — not just the
+# offending line — unless root owns it and no one else can write it:
+#
+#     sudo install -Dm644 -o root -g root actions.conf.example \
+#          /etc/fingerprintd/actions.conf
+#
+# It is read once, at startup. Editing it means restarting the unit, which is
+# also when you get to see the parse errors.
+#
+# Format, four fields:
+#
+#   <finger>  <where>  <verdict>  <command...>
+#
+#   finger    an fprintd finger name: left-thumb, left-index-finger,
+#             left-middle-finger, left-ring-finger, left-little-finger, and
+#             the right-* equivalents.
+#
+#   where     system   root runs the command below.
+#             session  no command here. The daemon emits
+#                      net.catcrafts.Fingerprintd1.FingerMatched(finger, uid)
+#                      and an agent in your session decides what it means.
+#                      This is how you launch an application: root has no
+#                      session bus and no display, and running your software
+#                      as root to get one would be a poor trade.
+#
+#   verdict   match     the client is told the finger matched. Normal.
+#             no-match  the client is told it did NOT, whatever really
+#                       happened, while the action runs anyway.
+#
+#   command   an ABSOLUTE path, required for system, forbidden for session.
+#             It is passed to /bin/sh -c with a fixed environment plus
+#             FINGERPRINTD_FINGER. It is double-forked, so it may outlive the
+#             daemon and will never delay an unlock.
+#
+# A finger with no line here is untouched.
+
+# --- Launching things in your session -----------------------------------
+# The daemon only announces the finger; your agent maps it to an app.
+#right-ring-finger    session  match
+
+# --- A duress finger ------------------------------------------------------
+# The phone reports that it did not recognise this finger, and runs the
+# script anyway. Think carefully before making that script destructive:
+#
+#   * a false accept that opens a camera is a shrug; one that wipes is not,
+#   * and anyone who can compel one unlock can usually compel a second, so
+#     this is a panic button, not protection for data at rest. Only
+#     encryption is that, and by unlock time your session is already
+#     decrypted in RAM.
+#
+#left-little-finger   system   no-match  /etc/fingerprintd/panic.sh
+
+# --- Something harmless to try it with ------------------------------------
+#left-thumb           system   match     /usr/bin/logger -t fingerprintd "thumb"

packaging/fingerprint-auth.pam

@@ -0,0 +1,32 @@
+#%PAM-1.0
+# SPDX-License-Identifier: GPL-3.0-only
+# SPDX-FileCopyrightText: Copyright (C) 2026 Catcrafts®
+#
+# The service kscreenlocker's /etc/pam.d/kde-fingerprint substacks, and which
+# nothing on Alpine provides -- so on a stock pmOS image every fingerprint
+# unlock fails before it reaches any daemon, with PAM unable to open the
+# substack rather than anything about fingerprints. kscreenlocker ships
+# kde-fingerprint (auth/account/password/session all `include fingerprint-auth`)
+# and Alpine ships pam_fprintd, and the file joining them is simply absent.
+#
+# It lives in the vendor directory /usr/lib/pam.d, next to Alpine's own
+# base-auth, so an administrator can still override it in /etc/pam.d.
+#
+# fingerprintd ships it because fingerprintd is what makes it mean anything:
+# this package provides fprintd, so it owns the bus name pam_fprintd talks to.
+
+# pam_fprintd asks the daemon to verify, prompting through the PAM
+# 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.
+auth       required    pam_env.so
+auth       sufficient  pam_fprintd.so
+auth       required    pam_deny.so
+
+account    include     base-account
+
+# A fingerprint cannot set a password, and kde-fingerprint includes this
+# service for `password` as well.
+password   required    pam_deny.so
+
+session    include     base-session

packaging/make-bin-tarball.sh

@@ -25,6 +25,8 @@ cp packaging/fingerprintd.service \
    packaging/fingerprintd.modules-load.conf \
    packaging/fingerprintd.json \
    packaging/20-focal64.manifest \
+   packaging/fingerprint-auth.pam \
+   packaging/actions.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))"

packaging/net.reactivated.Fprint.conf

@@ -18,4 +18,12 @@
     <allow send_destination="net.reactivated.Fprint"/>
     <allow receive_sender="net.reactivated.Fprint"/>
   </policy>
+  <!-- net.catcrafts.Fingerprintd1.FingerMatched is ours, not fprintd's: it
+       names the finger that just matched so an agent in the user's session
+       can act on it. It is carried by the receive_sender rule above, which
+       means any local user can see which finger the owner used and when.
+       That is a real if small leak, and it is the price of letting an
+       unprivileged session agent hear it at all, since D-Bus cannot address
+       a signal to one uid. Acceptable on a single-user phone; a multi-user
+       system should narrow the rule above to the intended uid. -->
 </busconfig>