fingerprintd/packaging/fplearn.sh

#!/bin/sh
# fplearn.sh -- the template-learning measurement, as a protocol rather than a
# pile of remembered commands.
#
#   fplearn.sh snapshot [name]     save the current template aside (forensics
#                                  only -- see restore)
#   fplearn.sh restore  <name>     REFUSES: a restore DESTROYS the template on
#                                  this device, see the note in the command
#   fplearn.sh wipe                 remove every stored template (backup first)
#   fplearn.sh enrol  [finger]     enrol at the config's sample count
#   fplearn.sh base   [n] [w]      trial with learning OFF  (the baseline)
#   fplearn.sh trend  [n] [w]      three trials with learning ON
#   fplearn.sh sizes                just print the template container sizes
#
# SNAPSHOT BEFORE EVERY MEASUREMENT BLOCK. Learning rewrites the template in
# place, so without a snapshot an improvement cannot be attributed: a rate that
# climbs over an evening is equally explained by the template getting better, by
# the SENSOR being wiped clean, or by the USER learning where the sensor likes
# to be pressed (Jorijn, 2026-09-04, having spotted both while the numbers were
# still going up). All three move the same way on the same time axis.
#
# A snapshot makes the paired test possible: measure the learned template, then
# restore the older one and measure again WITHIN THE SAME SESSION, so the sensor
# is equally clean and the user equally practised for both halves. A rate that
# falls back on restore is learning. A rate that stays up is not.
#
# WIPE FIRST when re-enrolling a finger that is already in the group. Measured
# 2026-09-04: the duplicated-finger check refuses a finger the group already
# holds -- 0 accepted of 7 presses, rc=0 on every one, while a never-enrolled
# finger progressed normally. Since 0.2.6 the daemon removes a re-enrolled
# finger's old template itself before ENROLL (in a managed group, on a map it
# read in full). This protocol still starts from a wiped group, so that the
# template it measures has no history: `enrol` refuses a finger name that is
# already in the map and points here.
#
# WHY IT IS SHAPED LIKE THIS. Learning is cumulative: every matched press folds
# frames into the stored template, so a second run is not a repeat of the first
# and an A/B against a moving template is not an A/B at all. The only honest
# comparison is on ONE template lineage, in order:
#
#   1. enrol            a fresh template, 20 samples, no position prompts --
#                       which is also the outstanding replication of the 7/10
#                       result, the one measurement this lane was parked on
#   2. base             learning off: the clean number for THIS template, and
#                       the only figure comparable to every rate in the journal
#   3. trend            learning on, three times: the rate should climb, and
#                       the container size is an independent witness that it
#                       is the template moving and not the weather
#
# Do NOT read run 1 of the trend as "learning made it better". Run 1 starts on
# the same template the baseline ended on; it is the first run that can improve
# it, not one that has already been improved.
set -u

GROUP=/mnt/persist/data/RIY7A+mQm3EA4FsCUmkJo0b9dFUYP2YZ4P5hmMiZgeA_Alt
MAP=/var/lib/fingerprintd/fingers-10000.map
UNIT=fingerprintd-test
BIN=/tmp/fingerprintd
COMMON="--daemon --verbose --edge-wake --sfs-root=/var/lib/fingerprintd/sfs --sfs-writable --rpmb-write"

# How many frames learning actually folded, out of the daemon's own transcript.
# Without this a trend run cannot tell "learning fired and did not help" from
# "learning never fired" -- which is exactly the confusion that made the first
# trend run measure a static template three times.
folds() {
    L=$(ls -t /var/log/fingerprintd/*.log 2>/dev/null | head -1)
    [ -n "$L" ] || { echo "  (no transcript)"; return; }
    m=$(grep -c -- "-> MATCH fid=" "$L" 2>/dev/null || echo 0)
    f=$(grep -c "folded in (metric" "$L" 2>/dev/null || echo 0)
    s=$(grep -c "learn: template saved" "$L" 2>/dev/null || echo 0)
    echo "  folds: $f frame(s) over $m matched press(es), $s save(s)"
}

sizes() {
    # A template is stored twice, the container and its backup, so the sizes
    # come in pairs. The BODY is the container minus its 4096-byte header.
    sudo ls -la "$GROUP" 2>/dev/null | awk '$5 > 200000 { printf "  %9d  body %9d  %s\n", $5, $5-4096, $9 }' | sort -u
}

restart() {  # $1 = extra args
    sudo systemctl stop "$UNIT" 2>/dev/null
    sleep 2
    sudo systemd-run --unit="$UNIT" --collect $BIN $COMMON $1 >/dev/null 2>&1
    printf 'daemon starting'
    i=0
    while [ $i -lt 40 ]; do
        if busctl --system list 2>/dev/null | grep -q net.reactivated.Fprint; then
            # Owning the name is not the same as being ready: the session comes
            # up on the worker thread afterwards.
            sleep 6; printf ' ready\n'; return 0
        fi
        printf '.'; sleep 1; i=$((i+1))
    done
    printf ' TIMED OUT\n'; return 1
}

# NOT $HOME: this script is run under sudo, where HOME is root's, so snapshots
# silently landed in /root/fp6-backups and `ls ~/fp6-backups/snapshots` said
# they did not exist. Resolve the INVOKING user's home instead.
SNAPHOME=$(getent passwd "${SUDO_USER:-$(id -un)}" | cut -d: -f6)
SNAPDIR=${SNAPHOME:-$HOME}/fp6-backups/snapshots

case "${1:-}" in
snapshot)
    NAME=${2:-$(date +%Y%m%d-%H%M%S)}
    D=$SNAPDIR/$NAME
    mkdir -p "$D"
    n=0
    for f in $(sudo ls "$GROUP"); do
        sz=$(sudo stat -c %s "$GROUP/$f")
        if [ "$sz" -gt 200000 ]; then sudo cp -p "$GROUP/$f" "$D/$f"; n=$((n+1)); fi
    done
    sudo cp -p "$MAP" "$D/" 2>/dev/null || true
    sudo chown -R "$(id -u):$(id -g)" "$D"
    echo "snapshot '$NAME': $n container(s)"
    ls -la "$D" | awk 'NR>3{printf "  %9d  %s\n", $5, $9}'
    echo "restore with: fplearn.sh restore $NAME" ;;

restore)
    # DISABLED, and it must stay disabled: restoring a template DESTROYS it.
    #
    # Measured 2026-09-05. A byte-exact restore of an earlier container made the
    # trustlet read its header, UNLINK it, look for a .bak, and bump the RPMB
    # counter -- for both containers. The enrolled finger was gone, and no copy
    # can bring it back, because QTEE binds every SFS object to a hardware
    # anti-rollback counter that has since advanced. An older container is not
    # stale to QTEE, it is TAMPERED, and the response to tampering is deletion.
    #
    # So the paired within-session comparison this was built for is IMPOSSIBLE
    # on this hardware. A template can be measured, and it can be replaced by
    # enrolling again, but it can never be put back.
    cat <<'WARN'
REFUSING: restoring a template DESTROYS it on this device.

QTEE binds every stored object to a hardware anti-rollback counter. An earlier
container is not stale to it, it is tampered, and it responds by UNLINKING the
file. Measured 2026-09-05: a byte-exact restore of the previous template made
the trustlet unlink BOTH containers and advance the RPMB counter. The enrolled
finger was destroyed and no copy could bring it back.

Snapshots are still worth taking -- they are forensic evidence of what a
template looked like -- but they cannot be put back. To change the template,
enrol again.
WARN
    exit 1 ;;

restore-force-DESTRUCTIVE)
    NAME=${2:-}
    D=$SNAPDIR/$NAME
    [ -n "$NAME" ] && [ -d "$D" ] || { echo "usage: fplearn.sh restore <name>"; echo "available:"; ls "$SNAPDIR" 2>/dev/null | sed 's/^/  /'; exit 1; }
    echo "=== restore snapshot '$NAME' ==="
    echo "before:"; sizes
    # The trustlet holds the template in memory once loaded, so a restore that
    # does not restart the daemon changes the file and nothing else.
    sudo systemctl stop "$UNIT" 2>/dev/null; sleep 2
    for f in $(ls "$D"); do
        case "$f" in fingers-*.map) sudo cp -p "$D/$f" "$MAP" ;;
                     *) sudo cp -p "$D/$f" "$GROUP/$f" ;; esac
    done
    sudo sync
    restart "--learn=0" || exit 1
    echo "after:"; sizes
    fprintd-list user 2>&1 | tail -1
    echo
    echo "Daemon is up with learning OFF, so the restored template stays put."
    echo "Measure it now, in this session, against the block you just ran:"
    echo "  fplearn.sh base" ;;

sizes)
    echo "template containers now:"; sizes ;;

wipe)
    # The procedure of 2026-09-03 and 2026-09-04, and its reasoning: ONLY the
    # template containers go (>200000 bytes; each template is stored twice).
    # The 1588-byte group index is KEPT -- deleting it risks the RPMB
    # anti-rollback counters going stale against object ids QTEE would then
    # recreate, which already cost an index restore once -- and a missing
    # template container is the known-good "not exist, skip" case. The daemon
    # is stopped first so the trustlet reloads from the store, and a backup is
    # taken first because a template is not reproducible without a finger.
    echo "=== wipe: every stored template ==="
    echo "before:"; sizes
    D=${SNAPHOME:-$HOME}/fp6-backups/$(date +%Y-%m-%d-%H%M)-pre-wipe
    mkdir -p "$D"
    sudo tar -cf "$D/persist-data.tar" -C /mnt/persist data
    sudo cp "$MAP" "$D/" 2>/dev/null || true
    sudo chown -R "$(id -u):$(id -g)" "$D"
    echo "backup: $D ($(tar -tf "$D/persist-data.tar" | wc -l) entries, $(sha256sum "$D/persist-data.tar" | cut -c1-16))"
    sudo systemctl stop "$UNIT" 2>/dev/null; sleep 2
    n=0
    for f in $(sudo ls "$GROUP"); do
        sz=$(sudo stat -c %s "$GROUP/$f")
        if [ "$sz" -gt 200000 ]; then sudo rm -f "$GROUP/$f"; n=$((n+1)); fi
    done
    sudo sync
    sudo sh -c ": > $MAP"
    echo "removed $n container(s); index and small containers kept; map cleared"
    # Off, like enrol: a wipe is the start of a controlled sequence, and coming
    # back with learning on invites the next thing that verifies to start
    # folding before anyone intended it.
    restart "--learn=0" || exit 1
    fprintd-list user 2>&1 | tail -1
    echo "after:"; sizes
    echo; echo "next: fplearn.sh enrol <finger>" ;;

enrol)
    F=${2:-right-middle-finger}
    if sudo grep -q "^$F " "$MAP" 2>/dev/null; then
        echo "$F is already enrolled (in $MAP)."
        echo "This protocol measures a template with no history; run"
        echo "  fplearn.sh wipe"
        echo "first. (The daemon replaces a re-enrolled finger's template by itself since 0.2.6.)"
        exit 1
    fi
    echo "=== enrol $F ==="
    echo "sizes before:"; sizes
    # Learning OFF for the enrolment itself. Enrolment does not use it, and a
    # daemon left with it on will start folding into the brand-new template the
    # moment anything verifies -- which is exactly the contamination a
    # fresh-template control exists to avoid. `trend` turns it back on.
    restart "--learn=0" || exit 1
    /tmp/fpenrol.sh "$F"
    echo; echo "sizes after the enrolment:"; sizes
    echo; echo "next: fplearn.sh base" ;;

base)
    N=${2:-15}; W=${3:-0}
    echo "=== BASELINE: learning OFF ==="
    restart "--learn=0" || exit 1
    echo "sizes before:"; sizes
    /tmp/fptrial.sh "$N" "$W"
    echo; echo "sizes after (MUST be unchanged -- learning was off):"; sizes
    echo; echo "next: fplearn.sh trend" ;;

trend)
    # No wrong-finger taps by default: zero false accepts is settled over forty
    # of them, and the presses are better spent on the false-negative rate.
    N=${2:-15}; W=${3:-0}
    echo "=== TREND: learning ON, three runs on one template ==="
    restart "--learn=1" || exit 1
    echo "sizes at the start:"; sizes
    r=1
    while [ $r -le 3 ]; do
        echo; echo "----- learning run $r of 3 -----"
        /tmp/fptrial.sh "$N" "$W"
        echo "after run $r:"; sizes; folds
        r=$((r+1))
    done
    echo
    echo "Read it as a trend, not three numbers. A rate that climbs while the"
    echo "container grows is learning; a rate that moves while the container"
    echo "does not is noise, and the daemon's own 'learn:' lines say which." ;;

*)
    sed -n '2,52p' "$0"; exit 1 ;;
esac