From 135aab2e54a331001ed43f4e76fc0b6be676d4c7 Mon Sep 17 00:00:00 2001 From: Derek Ross Date: Mon, 2 Nov 2026 17:50:29 -0500 Subject: [PATCH 01/15] omamobile-fingerprint 0.1.14: consent, read-only copies, TDP guard, one start per boot Fingerprint is to work out of the box on a new install, so the runner, not a person following a runbook, now carries the safety that F3/F4 gave: - The storage stage refuses without the owner's install-time acknowledgement (/etc/omamobile/fingerprint.conf, CONSENT=yes; a missing file or key is no), unless this install's secure storage already exists (the bring-up phones, whose first run had the human's go). - At the first start it makes the read-only copies itself: mfg_data with dd, persist:/ss/0 and /ss/nsp with debugfs (no mount, no journal replay), both partitions required ro=1 and persist not mounted read-write, and records their sha256 in /var/lib/omamobile-fp/provenance. Until now nothing on a new install made these copies, so a start served an empty TDP against stock's RPMB anchor. - No storageproxyd without the TDP copy, and none once the copy or persist:/ss/0 differs from the recorded hash. This refuses rather than warns: once Linux (or a stock boot) has written TDP, every further start moves the RPMB anchor further from what stock would read, and only the maintainer can judge what is safe then. The design note left this open; refusing keeps the state as it was found. - One storage proxy per boot: a marker in /run refuses a second start with "reboot". On 2026-11-02 a proxy stopped and restarted twice between TD's clear and its first commit asserted Trusty's storage app (block_get_cleared_super) and halted Trusty. The unit drops Restart= and the start limit, uses KillMode=mixed, and the runner stops the bridge and HAL first, KeyMint and Gatekeeper next, storageproxyd last. test/preflight runs each case against a fake tree. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BeEcdVeSfyLCbijF8XQF1d --- packages/omamobile-fingerprint/PKGBUILD | 2 +- .../lib/omamobile-fp-chroot | 260 +++++++++++++++++- .../omamobile-fingerprint.install | 10 +- packages/omamobile-fingerprint/test/all | 16 ++ packages/omamobile-fingerprint/test/preflight | 159 +++++++++++ .../systemd/system/omamobile-fp.service | 22 +- packages/omamobile-fingerprint/version | 2 +- 7 files changed, 447 insertions(+), 24 deletions(-) create mode 100755 packages/omamobile-fingerprint/test/preflight diff --git a/packages/omamobile-fingerprint/PKGBUILD b/packages/omamobile-fingerprint/PKGBUILD index e8b882d85..68edcf025 100644 --- a/packages/omamobile-fingerprint/PKGBUILD +++ b/packages/omamobile-fingerprint/PKGBUILD @@ -8,7 +8,7 @@ arch=(aarch64) url="https://github.com/derekross/omarchy-mobile" license=(MIT) backup=(etc/pam.d/omarchy-lock-fingerprint) -depends=(bash python util-linux coreutils systemd kmod fprintd) +depends=(bash python util-linux coreutils systemd kmod fprintd e2fsprogs) optdepends=('fprintd: fingerprint unlock and sudo through PAM' 'libfprint: the Omarchy Mobile build, with the omamobile_udfps driver') install=omamobile-fingerprint.install diff --git a/packages/omamobile-fingerprint/lib/omamobile-fp-chroot b/packages/omamobile-fingerprint/lib/omamobile-fp-chroot index 3c753d475..ce7e7f9e1 100755 --- a/packages/omamobile-fingerprint/lib/omamobile-fp-chroot +++ b/packages/omamobile-fingerprint/lib/omamobile-fp-chroot @@ -5,6 +5,11 @@ # bring-up runbook in FINGERPRINT-PLAN.md). # # omamobile-fp-chroot check preconditions only; changes nothing +# omamobile-fp-chroot preflight the safety checks a start runs before +# storageproxyd (consent, the read-only +# copies, the TDP guard, once per boot); +# on success it counts as this boot's +# start (start runs it itself) # omamobile-fp-chroot start [STAGE] start the stack up to STAGE, in the # foreground (systemd runs it), and # supervise it until stopped @@ -25,6 +30,29 @@ # read-only, and only $STATE (Trusty's secure storage files, the HAL's data) # persists. It shares the host's network namespace on purpose: the sensor # driver's netlink socket exists only in the initial one. +# +# Safety before storageproxyd (preflight; FINGERPRINT-PLAN F19 and +# section 4). Every start runs storageproxyd, and Trusty's storage writes +# the RPMB, so: +# - consent: the storage stage runs only when /etc/omamobile/fingerprint.conf +# says CONSENT=yes (omamobile-firstboot writes it from the installer's +# acknowledgement; a missing file or key is no), or when this install's +# secure storage already exists (a phone whose first run had the human's +# go during bring-up); +# - the read-only copies (the 7 Pro): at the first start it copies +# mfg_data (dd) and persist:/ss/0 and /ss/nsp (debugfs, which reads the +# partition without mounting it) into $STATE and records their sha256 in +# $STATE/provenance. Both partitions must read ro=1 (the storage guard) +# and persist must not be mounted read-write; +# - the TDP guard: no storageproxyd without the TDP copy (an empty TDP +# against stock's RPMB anchor could break stock's persistent store for +# good), and none once the copy, or persist:/ss/0 itself, no longer +# matches the recorded hash: Linux or a stock boot changed TDP, and going +# on would bury that under more writes (FINGERPRINT-PLAN F19); +# - once per boot: Trusty keeps each store's state for the whole boot, and +# a storage proxy stopped and started again in the same boot crashed +# Trusty's storage app on 2026-11-02 (FINGERPRINT-PLAN F19). A marker in +# /run refuses a second start until a reboot. set -euo pipefail IMAGE=${OMAMOBILE_FP_IMAGE:-/usr/lib/omamobile-fp/root} @@ -68,7 +96,17 @@ esac PANEL_NAME=${OMAMOBILE_FP_PANEL_NAME:-$PANEL_NAME} PROPS_DEVICE=${OMAMOBILE_FP_PROPS_DEVICE:-/usr/lib/omamobile-fp/props-$DEVICE.conf} STATE=${OMAMOBILE_FP_STATE:-/var/lib/omamobile-fp} -RUN=/run/omamobile-fp +RUN=${OMAMOBILE_FP_RUN:-/run/omamobile-fp} +# The owner's install-time acknowledgement (omamobile-firstboot writes it). +CONSENT=${OMAMOBILE_FP_CONSENT:-/etc/omamobile/fingerprint.conf} +# Where the partitions are found (tests point these at a fake tree). +SYSBLOCK=${OMAMOBILE_FP_SYSBLOCK:-/sys/class/block} +DEVDIR=${OMAMOBILE_FP_DEVDIR:-/dev} +MOUNTS=${OMAMOBILE_FP_MOUNTS:-/proc/mounts} +PROVENANCE=$STATE/provenance +# Set once storageproxyd may have started this boot; /run goes with the +# reboot, which is exactly when Trusty's state does. +MARKER=$RUN/storageproxyd-started ROOT=$RUN/root NSPID=$RUN/ns.pid @@ -96,18 +134,50 @@ die() { say "error: $*"; exit 1; } # env(1) would look chroot up in that. CHROOT_BIN=$(PATH=/usr/bin:/bin:/usr/sbin:/sbin command -v chroot || true) +# A supervised child still running (not gone, not a zombie)? +alive() { + local st + st=$(sed 's/^.*) //' "/proc/$1/stat" 2>/dev/null) || return 1 + [[ -n $st && ${st%% *} != Z ]] +} + +# TERM the named children, then wait up to $1 tenths of a second for them. +stop_children() { + local tenths=$1 n p i any; shift + for n in "$@"; do + p=${PIDS[$n]:-} + [[ -n $p ]] && kill -TERM "$p" 2>/dev/null || true + done + for ((i = 0; i < tenths; i++)); do + any=0 + for n in "$@"; do + p=${PIDS[$n]:-} + [[ -n $p ]] && alive "$p" && any=1 + done + ((any)) || return 0 + sleep 0.1 + done + say "still running after $((tenths / 10)) s: $*" +} + # Stop everything once: ignore further TERM/INT first, so the group-wide -# kill below cannot re-enter this handler, then signal the process group -# and exit. As the namespace's PID 1, exiting also ends every process left. +# kill below cannot re-enter this handler. The bridge and the HALs go first, +# and storageproxyd last, so no trusted-app commit is in flight when the +# proxy disappears (a proxy killed under a live TA left Trusty's storage +# inconsistent on 2026-11-02, FINGERPRINT-PLAN F19). Then the process group, +# and exit: as the namespace's PID 1, exiting also ends every process left. STOPPING= stop() { local code=${1:-0} [[ -n $STOPPING ]] && exit "$code" STOPPING=1 trap '' TERM INT - say "stopping" + say "stopping: the bridge and the HALs first, the storage proxy last" # no capture runs any more: the desktop drops its target rm -f "$UIDIR/state.json" "$UIDIR/state.json.new" + stop_children 100 bridge fingerprint + stop_children 50 gatekeeper keymint + stop_children 50 storageproxyd kill -TERM 0 2>/dev/null || true exit "$code" } @@ -145,12 +215,171 @@ check() { sg=$(rpmb_sg) [[ -n $sg ]] || { say "no SCSI generic node for the RPMB LUN $RPMB_LUN (modprobe sg)"; ok=0; } [[ -n $sg ]] && say "RPMB: /dev/$sg" - [[ -f $STATE/mfg_data.img ]] || - say "no $STATE/mfg_data.img: the HAL will run without factory calibration" + if ((MAP_STORES)); then + [[ -f $STATE/mfg_data.img ]] || + say "no $STATE/mfg_data.img: the HAL will run without factory calibration" + else + [[ -f $STATE/mfg_data.img ]] || + say "no $STATE/mfg_data.img yet: the first start copies it from mfg_data" + fi + if consent_given; then say "consent: yes ($CONSENT)" + elif storage_exists; then say "consent: no record, but this install's secure storage already exists" + else say "consent: no (no CONSENT=yes in $CONSENT): the storage stage will refuse"; fi + [[ ! -e $MARKER ]] || say "storageproxyd already started this boot: a new start needs a reboot" ((ok)) || exit 1 say "preconditions met" } +# --- Safety before storageproxyd (see the header) --------------------------- + +# CONSENT=yes in the consent file. Data, never sourced; anything else is no. +consent_given() { + [[ -f $CONSENT ]] && grep -qx 'CONSENT=yes' "$CONSENT" +} + +# This install's TD already exists: storageproxyd ran here before (on the +# bring-up phones, with the human's go), so the irreversible first run is +# behind it. +storage_exists() { + [[ -s $STATE/data/vendor/ss/0 || -L $STATE/data/vendor/ss/0 || -f $STATE/td.img ]] +} + +# The block device name of a partition, by PARTNAME (the Arch root has no +# /dev/disk/by-partlabel). +part_dev() { + local f + for f in "$SYSBLOCK"/*/uevent; do + grep -qx "PARTNAME=$1" "$f" 2>/dev/null && { basename "$(dirname "$f")"; return 0; } + done + return 1 +} + +sha() { sha256sum "$1" | cut -d' ' -f1; } +recorded() { [[ ! -f $PROVENANCE ]] || awk -v n="$1" '$2 == n {print $1; exit}' "$PROVENANCE"; } + +# A partition fit to be read: found, read-only (the storage guard), and not +# mounted read-write. Prints its device name. +ro_part() { + local d + d=$(part_dev "$1") || die "no $1 partition (PARTNAME=$1 in $SYSBLOCK/*/uevent)" + [[ $(cat "$SYSBLOCK/$d/ro" 2>/dev/null) == 1 ]] || + die "$1 ($d) is not read-only: the storage guard must keep it ro=1. Nothing copied, nothing started" + if awk -v d="$DEVDIR/$d" '$1 == d && $4 ~ /(^|,)rw(,|$)/ {f = 1} END {exit !f}' "$MOUNTS" 2>/dev/null; then + die "$1 ($d) is mounted read-write. Nothing copied, nothing started" + fi + printf '%s\n' "$d" +} + +# Read one file out of persist's ext4 with debugfs: no mount, no journal +# replay, nothing written to the partition. Fails on an empty result. +persist_dump() { # $1 path in persist, $2 output, $3 the partition's device + rm -f "$2" + debugfs -R "dump -p $1 $2" "$DEVDIR/$3" >/dev/null 2>&1 || true + [[ -s $2 ]] +} + +# The 7 Pro's read-only copies, once (FINGERPRINT-PLAN F19.3, done by the +# runner): mfg_data and persist:/ss/{0,nsp} into $STATE, their sha256 +# recorded in $STATE/provenance. A phone set up by hand (copies there, no +# provenance) has its TDP copy checked against persist:/ss/0 and adopted. +provision() { + local p m tmp + [[ -f $PROVENANCE ]] && return 0 + p=$(ro_part persist) + m=$(ro_part mfg_data) + command -v debugfs >/dev/null || die "no debugfs (e2fsprogs): can't read persist without mounting it" + install -d -m 0700 "$STATE" "$STATE/persist-ss" + tmp=$STATE/.provision + rm -rf "$tmp" + install -d -m 0700 "$tmp" + if [[ -e $STATE/persist-ss/0 ]]; then + persist_dump /ss/0 "$tmp/0" "$p" || die "can't read persist:/ss/0 to check the existing TDP copy" + cmp -s "$tmp/0" "$STATE/persist-ss/0" || + die "$STATE/persist-ss/0 differs from persist:/ss/0: Linux's TDP copy and stock's no longer agree. Not starting: ask (FINGERPRINT-PLAN F19)" + say "the existing TDP copy matches persist:/ss/0: recording it" + else + persist_dump /ss/0 "$tmp/0" "$p" || + die "persist has no /ss/0 (or it can't be read): without a TDP copy storageproxyd won't start" + persist_dump /ss/nsp "$tmp/nsp" "$p" || + say "persist has no /ss/nsp: Trusty starts an empty one (it has no rollback check)" + mv "$tmp/0" "$STATE/persist-ss/0" + [[ ! -f $tmp/nsp ]] || mv "$tmp/nsp" "$STATE/persist-ss/nsp" + say "copied persist:/ss read-only (debugfs; persist is never mounted)" + fi + if [[ ! -s $STATE/mfg_data.img ]]; then + dd if="$DEVDIR/$m" of="$tmp/mfg_data.img" bs=1M status=none || die "can't read mfg_data" + [[ -s $tmp/mfg_data.img ]] || die "mfg_data read empty" + chmod 0600 "$tmp/mfg_data.img" + mv "$tmp/mfg_data.img" "$STATE/mfg_data.img" + say "copied mfg_data read-only (the factory calibration; the partition is never written)" + fi + rm -rf "$tmp" + { + echo "# omamobile-fp-chroot: read-only copies, $(date -Is 2>/dev/null || date). Never edit." + echo "$(sha "$STATE/persist-ss/0") persist-ss/0" + [[ ! -f $STATE/persist-ss/nsp ]] || echo "$(sha "$STATE/persist-ss/nsp") persist-ss/nsp" + echo "$(sha "$STATE/mfg_data.img") mfg_data.img" + } > "$PROVENANCE.new" + chmod 0600 "$PROVENANCE.new" + mv "$PROVENANCE.new" "$PROVENANCE" + say "recorded in $PROVENANCE: $(awk '!/^#/ {printf "%s %.16s ", $2, $1}' "$PROVENANCE")" +} + +# No storageproxyd without a TDP copy that still matches its recorded hash, +# and a persist:/ss/0 that still matches it too. A difference refuses the +# start rather than warning: once Linux has written TDP (or stock has, after +# a slot A boot), every further start moves the RPMB anchor on from the +# copy stock would read, and only the maintainer can decide what is safe. +tdp_guard() { + local want got p tmp + if ((MAP_STORES)); then + # the 9a: TDP is tdp.img, the F3 copy of trusty_persist (before the + # first mapped run, that copy as persist-ss/0) + [[ -f $STATE/tdp.img || ( -f $STATE/persist-ss/0 && ! -L $STATE/persist-ss/0 && -s $STATE/persist-ss/0 ) ]] || + die "no TDP copy ($STATE/tdp.img): storageproxyd won't start without it (device/tegu/FINGERPRINT-PLAN.md F4b)" + return 0 + fi + [[ -s $STATE/persist-ss/0 ]] || + die "no TDP copy ($STATE/persist-ss/0, recorded in $PROVENANCE): storageproxyd won't start without it. Don't recreate it by hand: ask (FINGERPRINT-PLAN F19)" + want=$(recorded persist-ss/0) + [[ -n $want ]] || die "$PROVENANCE has no persist-ss/0 line" + got=$(sha "$STATE/persist-ss/0") + [[ $got == "$want" ]] || + die "the TDP copy changed (sha256 ${got:0:16}, recorded ${want:0:16}): Linux wrote Trusty's persistent store, so stock's persist:/ss/0 no longer matches the RPMB. Refusing to start: report it (FINGERPRINT-PLAN F19)" + p=$(ro_part persist) + install -d -m 0755 "$RUN" + tmp=$RUN/persist-ss0.check + persist_dump /ss/0 "$tmp" "$p" || die "can't read persist:/ss/0 to check it against the copy" + got=$(sha "$tmp") + rm -f "$tmp" + [[ $got == "$want" ]] || + die "persist:/ss/0 changed since the copy was made (sha256 ${got:0:16}, recorded ${want:0:16}; did stock Android run?): the copy no longer matches the RPMB. Refusing to start: ask (FINGERPRINT-PLAN F19)" + want=$(recorded mfg_data.img) + if [[ -n $want && -f $STATE/mfg_data.img && $(sha "$STATE/mfg_data.img") != "$want" ]]; then + say "warning: $STATE/mfg_data.img differs from its recorded copy (the partition itself is never written)" + fi + return 0 +} + +# Everything before storageproxyd. On success the marker is set: from here +# on this boot's storage proxy counts as started, even if a later step fails. +preflight() { + if [[ -e $MARKER ]]; then + die "secure storage already ran this boot ($(cat "$MARKER" 2>/dev/null || true)): Trusty keeps its storage state until a reboot, and a second storage proxy in the same boot can crash it. Reboot to start fingerprint again" + fi + if consent_given; then + say "consent: the owner's install-time acknowledgement ($CONSENT)" + elif storage_exists; then + say "no consent record in $CONSENT, but this install's secure storage already exists (its first run had the human's go)" + else + die "no consent for the first secure-storage write: $CONSENT has no CONSENT=yes (the installer's acknowledgement writes it). Nothing started" + fi + ((MAP_STORES)) || provision + tdp_guard + install -d -m 0755 "$RUN" + echo "$(date -Is 2>/dev/null || date) pid $$" > "$MARKER" +} + # Bind $1 onto $2 (created as a file or directory to match), optionally ro. bind() { local src=$1 dst=$2 mode=${3:-rw} @@ -325,12 +554,14 @@ spawn() { local libs=$LIBS_VENDOR [[ $kind == system ]] && libs=$LIBS_SYSTEM say "starting $name" + # The log prefix runs in a process substitution, so $! is the program + # itself (env and chroot exec it), which stop() signals by name. env -i PATH=/system/bin:/vendor/bin \ LD_LIBRARY_PATH="$libs" LD_PRELOAD=/omamobile/omamobile-fp-shim.so \ OMAMOBILE_FP_PROPS=/dev/__omamobile_props__ \ OMAMOBILE_FP_LOGLEVEL="${OMAMOBILE_FP_LOGLEVEL:-3}" \ ANDROID_ROOT=/system ANDROID_DATA=/data \ - "$CHROOT_BIN" "$ROOT" "$@" 2>&1 | sed -u "s/^/[$name] /" & + "$CHROOT_BIN" "$ROOT" "$@" > >(sed -u "s/^/[$name] /") 2>&1 & PIDS[$name]=$! } @@ -365,10 +596,17 @@ start() { [[ $stage == bridge && -z $(touch_event) ]] && die "no touchscreen ($TOUCH_NAME)" mkdir -p "$RUN" if [[ -z ${OMAMOBILE_FP_IN_NS:-} ]]; then + # Consent, the read-only copies, the TDP guard, once per boot: every + # stage starts storageproxyd. + preflight # Re-exec in a private mount namespace (and PID namespace, so the # Android processes die with us). Not a network namespace: see above. + # systemd signals only this process (KillMode=mixed); unshare hands + # TERM on to our PID 1, whose stop() takes the stack down in order. rm -f "$NSPID" - exec unshare --mount --propagation private --pid --fork --kill-child \ + local fwd=() + unshare --help 2>/dev/null | grep -c -- '--forward-signals' >/dev/null && fwd=(--forward-signals) + exec unshare --mount --propagation private --pid --fork --kill-child "${fwd[@]}" \ env OMAMOBILE_FP_IN_NS=1 "$0" start "$stage" fi # unshare's child: PID 1 inside, its parent is unshare outside. /run is @@ -433,7 +671,8 @@ start() { fi say "stage $stage running" - # Supervise: any child exiting stops the whole stack (systemd restarts it). + # Supervise: any child exiting stops the whole stack, and it stays stopped + # until a reboot (one storage proxy per boot; the unit has no Restart=). wait -n || true # wait also returns when TERM/INT arrives; then the trap is already stopping [[ -n $STOPPING ]] || say "a service exited" @@ -461,9 +700,10 @@ run() { case ${1:-} in check) check ;; + preflight) preflight ;; start) start "${2:-bridge}" ;; ns) shift; ns "$@" ;; run) shift; run "$@" ;; - *) echo "usage: omamobile-fp-chroot check | start [storage|apploader|keys|hal|bridge] | ns CMD... | run CMD..." >&2 + *) echo "usage: omamobile-fp-chroot check | preflight | start [storage|apploader|keys|hal|bridge] | ns CMD... | run CMD..." >&2 exit 2 ;; esac diff --git a/packages/omamobile-fingerprint/omamobile-fingerprint.install b/packages/omamobile-fingerprint/omamobile-fingerprint.install index d854e7deb..14e63df63 100644 --- a/packages/omamobile-fingerprint/omamobile-fingerprint.install +++ b/packages/omamobile-fingerprint/omamobile-fingerprint.install @@ -1,9 +1,11 @@ # SPDX-License-Identifier: MIT post_install() { - echo "omamobile-fingerprint: nothing enabled. Needs the vendor files in /usr/lib/omamobile-fp/root" - echo " (tools/extract-fingerprint-vendor on your computer), the fingerprint DT overlays," - echo " and the staged bring-up in device/cheetah/FINGERPRINT-PLAN.md before" - echo " systemctl enable --now omamobile-fp (its first run writes Trusty's secure storage)." + echo "omamobile-fingerprint: nothing enabled by the package. On a release install," + echo " omamobile-firstboot enables omamobile-fp from the owner's install-time" + echo " acknowledgement (/etc/omamobile/fingerprint.conf); it starts once Google's" + echo " files are in /usr/lib/omamobile-fp/root (tools/phone-provision). Its first" + echo " start copies persist:/ss and mfg_data read-only and writes Trusty's secure" + echo " storage; without the acknowledgement it refuses (FINGERPRINT-PLAN F19)." } post_upgrade() { systemctl daemon-reload 2>/dev/null || true diff --git a/packages/omamobile-fingerprint/test/all b/packages/omamobile-fingerprint/test/all index 6c444c94f..383f7dc84 100755 --- a/packages/omamobile-fingerprint/test/all +++ b/packages/omamobile-fingerprint/test/all @@ -62,6 +62,22 @@ PATH=$r/bin:$PATH OMAMOBILE_FP_ROOT=$r bash "$h" post rm -rf "$r" echo "ok - fprintd is restarted after a wake, unless Omarchy's own hook does it" +# The safety before storageproxyd: consent, the read-only copies, the TDP +# guard, one storage proxy per boot (test/preflight, a fake tree). +bash -n test/preflight || fail "syntax: test/preflight" +test/preflight || fail "the runner's preflight" +# start runs it before the namespace, for every stage +sed -n '/^start() {/,/^}/p' lib/omamobile-fp-chroot | grep -c '^ preflight$' >/dev/null || fail "start runs preflight" +# One start per boot: no automatic restart, the runner signalled alone +u=vendor/systemd/system/omamobile-fp.service +grep -c '^Restart=no$' "$u" >/dev/null || fail "the unit never restarts the stack" +grep -c -e '^Restart=on' -e '^Restart=always' -e '^StartLimitBurst' "$u" >/dev/null && fail "no restart loop in the unit" +grep -c '^KillMode=mixed$' "$u" >/dev/null || fail "systemd signals only the runner, which stops the stack in order" +# Stop order: the bridge and the HAL, then KeyMint and Gatekeeper, the proxy last +order=$(sed -n '/^stop() {/,/^}/p' lib/omamobile-fp-chroot | sed -n 's/^ *stop_children [0-9]* //p' | tr '\n' '|') +[[ $order == "bridge fingerprint|gatekeeper keymint|storageproxyd|" ]] || fail "stop order: $order" +echo "ok - one start per boot, no restart loop, the storage proxy stopped last" + if [[ ! -f prebuilt/omamobile-fp-shim.so ]]; then echo "ok - the rest # SKIP no bionic prebuilts in this checkout (built on the computer)" exit 0 diff --git a/packages/omamobile-fingerprint/test/preflight b/packages/omamobile-fingerprint/test/preflight new file mode 100755 index 000000000..7d6498056 --- /dev/null +++ b/packages/omamobile-fingerprint/test/preflight @@ -0,0 +1,159 @@ +#!/bin/bash +# SPDX-License-Identifier: MIT +# The runner's safety before storageproxyd (omamobile-fp-chroot preflight), +# against a fake tree: partitions found by PARTNAME in a fake sysfs, their +# contents as plain files, debugfs replaced by a stub that "dumps" from a +# directory standing in for persist's file system. Nothing real is read. +# +# no consent -> refused, nothing copied +# consent -> mfg_data and persist:/ss/{0,nsp} copied, hashed +# a second start -> refused until a reboot (the /run marker) +# the TDP copy missing -> refused (and never quietly recreated) +# no /ss/0 in persist -> refused +# the TDP copy changed -> refused +# persist:/ss/0 changed -> refused +# a writable partition -> refused +# existing secure storage -> allowed without the record (bring-up phones) +# the 9a without tdp.img -> refused +set -euo pipefail +cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." +RUNNER=$PWD/lib/omamobile-fp-chroot +fail() { echo "not ok - $*" >&2; exit 1; } +pass() { echo "ok - $*"; } + +t=$(mktemp -d) +trap 'rm -rf "$t"' EXIT + +# A fresh fake phone in $t/p: persist (sda5) and mfg_data (sda6), read-only. +phone() { + local p=$t/p + rm -rf "$p" + mkdir -p "$p/sys/sda5" "$p/sys/sda6" "$p/sys/sda7" "$p/dev" "$p/persistfs/ss" "$p/bin" "$p/etc" "$p/run" + printf 'MAJOR=8\nMINOR=5\nDEVNAME=sda5\nDEVTYPE=partition\nPARTNAME=persist\n' > "$p/sys/sda5/uevent" + printf 'MAJOR=8\nMINOR=6\nDEVNAME=sda6\nDEVTYPE=partition\nPARTNAME=mfg_data\n' > "$p/sys/sda6/uevent" + printf 'MAJOR=8\nMINOR=7\nDEVNAME=sda7\nDEVTYPE=partition\nPARTNAME=persist_b\n' > "$p/sys/sda7/uevent" + echo 1 > "$p/sys/sda5/ro"; echo 1 > "$p/sys/sda6/ro"; echo 1 > "$p/sys/sda7/ro" + echo "persist image" > "$p/dev/sda5" + head -c 65536 /dev/urandom > "$p/dev/sda6" + head -c 4096 /dev/urandom > "$p/persistfs/ss/0" + echo "nsp from stock" > "$p/persistfs/ss/nsp" + : > "$p/mounts" + # debugfs -R "dump -p SRC DST" DEV: copy from persistfs, and log the call + cat > "$p/bin/debugfs" <> "$p/debugfs.log" +[[ \$1 == -R ]] || exit 1 +read -r cmd flag src dst <<<"\$2" +[[ \$cmd == dump && \$flag == -p && \$3 == "$p/dev/sda5" ]] || exit 1 +[[ -f "$p/persistfs\$src" ]] && cp "$p/persistfs\$src" "\$dst" +exit 0 +EOF + chmod +x "$p/bin/debugfs" +} + +pf() { + PATH=$t/p/bin:$PATH \ + OMAMOBILE_FP_DEVICE=${DEV:-cheetah} OMAMOBILE_FP_STATE=$t/p/state \ + OMAMOBILE_FP_CONSENT=$t/p/etc/fingerprint.conf OMAMOBILE_FP_RUN=$t/p/run/omamobile-fp \ + OMAMOBILE_FP_SYSBLOCK=$t/p/sys OMAMOBILE_FP_DEVDIR=$t/p/dev OMAMOBILE_FP_MOUNTS=$t/p/mounts \ + "$RUNNER" preflight > "$t/out" 2>&1 +} +consent() { printf 'CONSENT=%s\nCONSENT_SOURCE=install-acknowledgement\nCONSENT_DATE=2026-11-02\n' "$1" > "$t/p/etc/fingerprint.conf"; } +marker=$t/p/run/omamobile-fp/storageproxyd-started +S=$t/p/state + +# No consent: no file, CONSENT=no, a key that only looks like it +phone +pf && fail "no consent file: refused" +grep -c 'no consent' "$t/out" >/dev/null || { cat "$t/out"; fail "says why (no consent)"; } +[[ ! -e $S/persist-ss/0 && ! -e $S/mfg_data.img && ! -e $marker ]] || fail "nothing is copied or marked without consent" +consent no; pf && fail "CONSENT=no: refused" +printf 'CONSENT=yes # later\n' > "$t/p/etc/fingerprint.conf"; pf && fail "only an exact CONSENT=yes counts" +printf 'FINGERPRINT=yes\n' > "$t/p/etc/fingerprint.conf"; pf && fail "another key is not consent" +[[ ! -e $marker && ! -e $t/p/debugfs.log ]] || fail "persist is not even read without consent" +pass "no consent: refused, nothing read, copied or marked" + +# Consent: the copies are made, hashed and recorded; the marker is set +consent yes +pf || { cat "$t/out"; fail "consent: preflight passes"; } +cmp -s "$S/persist-ss/0" "$t/p/persistfs/ss/0" || fail "persist:/ss/0 copied" +cmp -s "$S/persist-ss/nsp" "$t/p/persistfs/ss/nsp" || fail "persist:/ss/nsp copied" +cmp -s "$S/mfg_data.img" "$t/p/dev/sda6" || fail "mfg_data copied" +for f in persist-ss/0 persist-ss/nsp mfg_data.img; do + [[ $(awk -v n="$f" '$2 == n {print $1}' "$S/provenance") == "$(sha256sum < "$S/$f" | cut -d' ' -f1)" ]] || + fail "provenance records the sha256 of $f" +done +[[ $(stat -c %a "$S/provenance") == 600 && $(stat -c %a "$S/mfg_data.img") == 600 ]] || fail "the copies are private" +[[ -e $marker ]] || fail "the once-per-boot marker is set" +grep -c 'dump -p /ss/0 ' "$t/p/debugfs.log" >/dev/null || fail "persist is read with debugfs" +grep -v -c 'debugfs -R dump -p ' "$t/p/debugfs.log" >/dev/null && fail "debugfs only dumps (no -w, no other request)" +pass "consent: mfg_data and persist:/ss copied read-only and their hashes recorded" + +# A second start in the same boot +pf && fail "a second start in the same boot is refused" +grep -c 'Reboot' "$t/out" >/dev/null || { cat "$t/out"; fail "says to reboot"; } +rm -f "$marker" # the reboot +pf || { cat "$t/out"; fail "after a reboot it starts again"; } +pass "one storage proxy per boot: a second start is refused until a reboot" + +# The TDP copy removed by hand: refused, not recreated +rm -f "$marker" "$S/persist-ss/0" +pf && fail "a missing TDP copy is refused" +grep -c 'no TDP copy' "$t/out" >/dev/null || { cat "$t/out"; fail "says the TDP copy is missing"; } +[[ ! -e $S/persist-ss/0 && ! -e $marker ]] || fail "the TDP copy is never quietly recreated" +pass "a missing TDP copy: refused, never recreated behind the record" + +# persist without /ss/0 on a new install +phone; consent yes; rm -f "$t/p/persistfs/ss/0" +pf && fail "no /ss/0 in persist: refused" +[[ ! -e $S/provenance && ! -e $marker ]] || fail "nothing recorded without a TDP copy" +pass "persist without /ss/0: refused, no TDP copy, no storage start" + +# The TDP copy changed after the record (Linux wrote TDP) +phone; consent yes; pf || fail "setup" +rm -f "$marker"; echo x >> "$S/persist-ss/0" +pf && fail "a changed TDP copy is refused" +grep -c 'TDP copy changed' "$t/out" >/dev/null || { cat "$t/out"; fail "says the TDP copy changed"; } +pass "the TDP copy changed since the record: refused" + +# persist:/ss/0 changed under the copy (a stock boot) +phone; consent yes; pf || fail "setup" +rm -f "$marker"; echo x >> "$t/p/persistfs/ss/0" +pf && fail "a changed persist:/ss/0 is refused" +grep -c 'persist:/ss/0 changed' "$t/out" >/dev/null || { cat "$t/out"; fail "says persist:/ss/0 changed"; } +pass "persist:/ss/0 changed since the copy: refused" + +# The storage guard: a writable or read-write mounted partition +phone; consent yes; echo 0 > "$t/p/sys/sda5/ro" +pf && fail "persist ro=0: refused" +grep -c "not read-only" "$t/out" >/dev/null || { cat "$t/out"; fail "says persist is not read-only"; } +phone; consent yes; echo 0 > "$t/p/sys/sda6/ro" +pf && fail "mfg_data ro=0: refused" +phone; consent yes; echo "$t/p/dev/sda5 /mnt ext4 rw,relatime 0 0" > "$t/p/mounts" +pf && fail "persist mounted read-write: refused" +grep -c "mounted read-write" "$t/out" >/dev/null || { cat "$t/out"; fail "says persist is mounted read-write"; } +[[ ! -e $S/mfg_data.img && ! -e $S/persist-ss/0 ]] || fail "nothing copied from an unguarded partition" +pass "a writable or read-write mounted partition: refused, nothing copied" + +# A bring-up phone: secure storage already there, copies by hand, no record +phone +mkdir -p "$S/data/vendor/ss" "$S/persist-ss" +head -c 1024 /dev/urandom > "$S/data/vendor/ss/0" +cp "$t/p/persistfs/ss/0" "$S/persist-ss/0"; cp "$t/p/dev/sda6" "$S/mfg_data.img" +pf || { cat "$t/out"; fail "existing secure storage starts without a consent record"; } +[[ -f $S/provenance ]] || fail "the hand-made TDP copy is checked and recorded" +phone +mkdir -p "$S/data/vendor/ss" "$S/persist-ss" +head -c 1024 /dev/urandom > "$S/data/vendor/ss/0" +echo other > "$S/persist-ss/0" +pf && fail "a hand-made TDP copy that differs from persist:/ss/0 is refused" +pass "bring-up phones: existing secure storage needs no record; the TDP copy is still checked" + +# The 9a (mapped stores): no tdp.img, no TDP +phone; consent yes +DEV=tegu pf && fail "tegu without tdp.img: refused" +mkdir -p "$S"; head -c 512 /dev/urandom > "$S/tdp.img" +DEV=tegu pf || { cat "$t/out"; fail "tegu with tdp.img passes"; } +pass "the 9a: refused without its TDP image" + +echo "omamobile-fingerprint preflight: ok" diff --git a/packages/omamobile-fingerprint/vendor/systemd/system/omamobile-fp.service b/packages/omamobile-fingerprint/vendor/systemd/system/omamobile-fp.service index 3245ab66a..63b59f1e1 100644 --- a/packages/omamobile-fingerprint/vendor/systemd/system/omamobile-fp.service +++ b/packages/omamobile-fingerprint/vendor/systemd/system/omamobile-fp.service @@ -2,8 +2,15 @@ # Google's fingerprint HAL, Trusty's storage proxy, KeyMint and Gatekeeper in # a minimal chroot, plus omamobile-fp-bridge, which fprintd's omamobile_udfps # driver talks to (device/cheetah/FINGERPRINT-PLAN.md). Not enabled by the -# package: the first run writes Trusty's secure storage (the RPMB), which -# the plan gates on the user's say-so (F4). +# package: omamobile-firstboot enables it on a phone whose owner acknowledged +# the secure-storage write at install time (/etc/omamobile/fingerprint.conf), +# and the runner refuses a first storage start without that record. +# +# One start per boot. Trusty keeps its storage state until a reboot, and a +# storage proxy stopped and started again in the same boot crashed Trusty's +# storage app on 2026-11-02 (FINGERPRINT-PLAN F19). So there is no Restart=, +# the runner refuses a second start until a reboot, and a failed unit stays +# failed: the lock screen uses the PIN, and a reboot starts it again. [Unit] Description=Omarchy Mobile fingerprint (vendor HAL and bridge) Documentation=file:///usr/share/doc/omamobile/FINGERPRINT-PLAN.md @@ -11,9 +18,6 @@ Documentation=file:///usr/share/doc/omamobile/FINGERPRINT-PLAN.md After=omamobile-aoc.service systemd-modules-load.service ConditionPathExists=/usr/lib/omamobile-fp/root ConditionPathExists=/dev/trusty-ipc-dev0 -# a HAL that keeps dying must not loop forever against the TA -StartLimitIntervalSec=300 -StartLimitBurst=5 [Service] # The sensor's rail is on pmic-2 (S2MPG13, bound through sec_acpm) and its @@ -24,9 +28,11 @@ StartLimitBurst=5 ExecStartPre=/usr/bin/modprobe sec_acpm ExecStartPre=/usr/bin/modprobe goodix_fp ExecStart=/usr/lib/omamobile-fp/omamobile-fp-chroot start bridge -KillMode=control-group -Restart=on-failure -RestartSec=10 +# TERM to the runner only: it stops the bridge and the HALs first and the +# storage proxy last; whatever is left after the timeout gets KILL. +KillMode=mixed +TimeoutStopSec=30 +Restart=no # The desktop's fingerprint target follows this file; a stack killed # outright cannot remove it itself. ExecStopPost=-/usr/bin/rm -f /run/omamobile-fp-ui/state.json diff --git a/packages/omamobile-fingerprint/version b/packages/omamobile-fingerprint/version index 7ac4e5e38..71d6a66ed 100644 --- a/packages/omamobile-fingerprint/version +++ b/packages/omamobile-fingerprint/version @@ -1 +1 @@ -0.1.13 +0.1.14 From b477983db5e543ada08d56792cc05046c2ade960 Mon Sep 17 00:00:00 2001 From: Derek Ross Date: Mon, 2 Nov 2026 17:53:07 -0500 Subject: [PATCH 02/15] install-phone: the wipe warning names fingerprint's secure-storage write, the codename acknowledges it The maintainer decided on 2026-11-02 that fingerprint works out of the box, with the install's one acknowledgement as the consent: no separate opt-in later. For a device whose ROOTFS_PACKAGES has omamobile-fingerprint, the warning before the codename gains one paragraph in plain words: the first start writes Trusty's area of the RPMB, can't be undone, is the same kind of write as an Android factory reset, touches neither persist, mfg_data, the Titan M2 nor slot A, and going back to stock works as usual with fingers enrolled again there. The acknowledgement is recorded in firstboot.conf as FINGERPRINT=yes and ACK_DATE (UTC). The file only reaches the phone after the codename is typed. --no-fingerprint (developers) records FINGERPRINT=no; a device without the package gets neither key. --help now prints every option. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BeEcdVeSfyLCbijF8XQF1d --- tests/install-phone | 37 +++++++++++++++++++++++++++++++++++++ tools/install-phone | 45 +++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 80 insertions(+), 2 deletions(-) diff --git a/tests/install-phone b/tests/install-phone index 78a3c1e26..5493f30ef 100755 --- a/tests/install-phone +++ b/tests/install-phone @@ -150,6 +150,43 @@ OMAMOBILE_FIRSTBOOT_ROOT=$t/fbroot "$SRC/packages/omamobile-firstboot/bin/omamob debugfs -R 'stat /etc/omamobile/boot-update.conf' "$flashed" 2>/dev/null | grep -q 'User: 0 Group: 0' || fail "boot-update.conf belongs to root" pass "the image copy gets a root-only firstboot.conf (hash, not password) and root's key, which firstboot accepts" +# Fingerprint: the warning before the codename names the secure-storage +# write, and the typed codename is recorded as the acknowledgement +flashed_conf() { + local f=$t/userdata.flashed + if command -v simg2img >/dev/null && [[ $(head -c4 "$f" | od -An -tx1 | tr -d ' ') == 3aff26ed ]]; then + simg2img "$f" "$t/flashed.img"; f=$t/flashed.img + fi + debugfs -R 'cat /etc/omamobile/firstboot.conf' "$f" 2>/dev/null +} +grep -q '^FINGERPRINT=\|^ACK_DATE=' <<<"$conf" && fail "a device without omamobile-fingerprint gets no FINGERPRINT line" +grep -q 'secure storage' "$t/out" && fail "a device without omamobile-fingerprint shows no fingerprint warning" +{ descriptor; echo 'ROOTFS_PACKAGES="omamobile-audio omamobile-fingerprint omamobile-modem"'; } > "$R/device/testdev/device.conf" +install || { cat "$t/out"; fail "a full run with fingerprint succeeds"; } +conf=$(flashed_conf) +grep -qx 'FINGERPRINT=yes' <<<"$conf" || fail "the acknowledgement is recorded as FINGERPRINT=yes" +grep -qx "ACK_DATE=$(date -u +%Y-%m-%d)" <<<"$conf" || fail "and dated (UTC)" +warn=$(grep -n 'writes the$' "$t/out" | head -1 | cut -d: -f1) +prompt=$(grep -n "Type the phone's codename" "$t/out" | head -1 | cut -d: -f1) +[[ -n $warn && -n $prompt ]] && ((warn < prompt)) || fail "the fingerprint warning comes before the codename is typed" +for words in "secure storage" "can't be undone" "factory reset" "persist" "mfg_data" "Titan M2" "enroll your fingers again"; do + grep -qF "$words" "$t/out" || fail "the fingerprint warning says: $words" +done +grep -q 'fingerprint: on' "$t/out" || fail "the plan shows fingerprint on" +printf '%s\n' "$conf" > "$t/fb.conf" +OMAMOBILE_FIRSTBOOT_ROOT=$t/fbroot "$SRC/packages/omamobile-firstboot/bin/omamobile-firstboot" --check "$t/fb.conf" > "$t/fb.out" || + fail "omamobile-firstboot accepts the acknowledgement" +grep -q '^fingerprint: on' "$t/fb.out" || fail "firstboot reads the acknowledgement" +install --no-fingerprint || { cat "$t/out"; fail "--no-fingerprint runs"; } +conf=$(flashed_conf) +grep -qx 'FINGERPRINT=no' <<<"$conf" || fail "--no-fingerprint records FINGERPRINT=no" +grep -q '^ACK_DATE=' <<<"$conf" && fail "--no-fingerprint records no acknowledgement" +grep -q 'secure storage' "$t/out" && fail "--no-fingerprint shows no fingerprint warning" +CONFIRM=cheetah install && fail "a wrong confirmation is refused with fingerprint on" +[[ -z $(flashing_calls) ]] || fail "nothing is flashed (and no acknowledgement leaves the laptop) without the codename" +descriptor > "$R/device/testdev/device.conf" +pass "fingerprint: the warning names the secure-storage write before the codename; the codename is recorded as FINGERPRINT=yes and ACK_DATE" + refuse() { local why=$1; shift if install "$@"; then cat "$t/out"; fail "refuses $why"; fi diff --git a/tools/install-phone b/tools/install-phone index 0adf5040b..b9a334351 100755 --- a/tools/install-phone +++ b/tools/install-phone @@ -53,6 +53,17 @@ # slot B is refused, since that is where stock # Android runs after a system update # --unsigned accept a bundle without SHA256SUMS.sig (development) +# --no-fingerprint developers: leave fingerprint off (FINGERPRINT=no); +# the phone's runner then refuses to write Trusty's +# secure storage +# +# Fingerprint (a device whose ROOTFS_PACKAGES has omamobile-fingerprint): the +# warning before the codename names the secure-storage write that its first +# start makes, and typing the codename acknowledges it with the wipe. That +# acknowledgement is recorded as FINGERPRINT=yes and ACK_DATE (UTC) in +# firstboot.conf; omamobile-firstboot turns it into +# /etc/omamobile/fingerprint.conf and enables the service +# (device/cheetah/FINGERPRINT-PLAN.md F19). # # Answers are read from standard input, so they can be piped for tests. set -euo pipefail @@ -71,10 +82,11 @@ say() { printf '\e[1m==> %s\e[0m\n' "$*"; } note() { printf ' %s\n' "$*"; } die() { printf '\e[31merror:\e[0m %s\n' "$*" >&2; exit 1; } -dry=0 device="" images="" rootfs="" work="" slots_match="" unsigned=0 reinstall=0 +dry=0 device="" images="" rootfs="" work="" slots_match="" unsigned=0 reinstall=0 no_fingerprint=0 while (($#)); do case $1 in --dry-run) dry=1 ;; + --no-fingerprint) no_fingerprint=1 ;; --device) device=${2:?}; shift ;; --images) images=${2:?}; shift ;; --rootfs) rootfs=${2:?}; shift ;; @@ -82,7 +94,7 @@ while (($#)); do --bootloader-slots-match) slots_match=${2:?}; shift ;; --reinstall) reinstall=1 ;; --unsigned) unsigned=1 ;; - -h|--help) sed -n '3,50p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0 ;; + -h|--help) sed -n '3,/^# Answers are read/p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0 ;; *) die "unknown argument $1 (see --help)" ;; esac shift @@ -484,6 +496,16 @@ while true; do done ssh_key=$(head -1 "$key_file") +# Fingerprint: on for a device that ships it, unless --no-fingerprint. The +# acknowledgement is the codename typed after the warning below; the file +# carrying it reaches the phone only after that. +fingerprint="" +if [[ " ${D[ROOTFS_PACKAGES]:-} " == *" omamobile-fingerprint "* ]]; then + fingerprint=yes + ((no_fingerprint)) && fingerprint=no +fi +ack_date=$(date -u +%Y-%m-%d) + # --- A local copy of the root image, with the owner's first-boot file ------- work=${work:-${XDG_CACHE_HOME:-$HOME/.cache}/omamobile-install} mkdir -p "$work" @@ -509,6 +531,11 @@ trap cleanup EXIT echo "WIFI_SSID=$wifi_ssid" [[ -n $wifi_psk ]] && echo "WIFI_PSK=$wifi_psk" fi + if [[ -n $fingerprint ]]; then + echo "FINGERPRINT=$fingerprint" + [[ $fingerprint == yes ]] && echo "ACK_DATE=$ack_date" + fi + true } > "$conf_file" printf '%s\n' "$ssh_key" > "$keys_file" printf '%s\n' "# Written by install-phone: a release install takes kernel updates through" \ @@ -582,6 +609,10 @@ note "user: $username ($credential), host $hostname, time zone $timezone" note "Wi-Fi: ${wifi_ssid:-none}" note "SSH key: ${ssh_key:0:40}... (root and $username)" note "root image: $(basename "$rootfs")" +case $fingerprint in + yes) note "fingerprint: on from the first start (see below)" ;; + no) note "fingerprint: off (--no-fingerprint)" ;; +esac echo echo "These commands, and only these, will run:" for p in $BOOT_IMAGES; do echo " fastboot flash ${p}_b $images/$p.img"; done @@ -593,6 +624,16 @@ echo "userdata will be ERASED: stock Android's data is lost, and stock Android o echo "slot A will need a factory reset if you ever boot it again. Slot A itself," echo "the bootloader, radio, persist, efs, modem and devinfo are not touched." echo +if [[ $fingerprint == yes ]]; then + echo "Fingerprint unlock is on from the first start. Its first start writes the" + echo "phone's secure storage (Trusty's area in the UFS RPMB). That can't be undone," + echo "but it is the same kind of write Android makes at every factory reset." + echo "Nothing is written to persist, the factory calibration (mfg_data), the" + echo "Titan M2 security chip or Android's slot A. Going back to Android works as" + echo "usual: Android starts like a new phone after its factory reset, and you" + echo "enroll your fingers again there." + echo +fi answer=$(ask "Type the phone's codename ($CODENAME) to go ahead") [[ $answer == "$CODENAME" ]] || die "not confirmed; nothing was written" From b2869973dcd907a67d760c7e0da7cf18cf22abdc Mon Sep 17 00:00:00 2001 From: Derek Ross Date: Mon, 2 Nov 2026 17:53:07 -0500 Subject: [PATCH 03/15] omamobile-firstboot 0.1.4: the install acknowledgement becomes fingerprint's consent record FINGERPRINT=yes (with ACK_DATE) in firstboot.conf is the owner's acknowledgement of fingerprint's secure-storage write, typed in the installer. Firstboot turns it into /etc/omamobile/fingerprint.conf (CONSENT=yes, CONSENT_SOURCE=install-acknowledgement, CONSENT_DATE), the record omamobile-fp-chroot requires before its first storage start, and enables omamobile-fp.service. Nothing is started: the unit stays inert until tools/phone-provision has pushed Google's files, and starts at the reboot INSTALL.md already asks for. A missing FINGERPRINT key (an older installer) is no, never consent; FINGERPRINT=yes without a date, a date without yes, or any other value is refused. The step is essential, so a failed write keeps firstboot.conf for the next boot rather than losing the acknowledgement. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BeEcdVeSfyLCbijF8XQF1d --- .../bin/omamobile-firstboot | 58 +++++++++++++++++-- packages/omamobile-firstboot/test/all | 32 ++++++++++ packages/omamobile-firstboot/version | 2 +- 3 files changed, 87 insertions(+), 5 deletions(-) diff --git a/packages/omamobile-firstboot/bin/omamobile-firstboot b/packages/omamobile-firstboot/bin/omamobile-firstboot index 39f4ea018..0f81f4e2f 100755 --- a/packages/omamobile-firstboot/bin/omamobile-firstboot +++ b/packages/omamobile-firstboot/bin/omamobile-firstboot @@ -24,7 +24,11 @@ # PIN or password exists, which it does here); # 9. Omarchy's user setup (omarchy-provision-user), then # omamobile-setup-user, as the user; -# 10. deletes firstboot.conf. +# 10. fingerprint, when the owner acknowledged its secure-storage write at +# install time (FINGERPRINT=yes): /etc/omamobile/fingerprint.conf, the +# record omamobile-fp-chroot requires, and omamobile-fp enabled (it +# starts once tools/phone-provision has added Google's files); +# 11. deletes firstboot.conf. # # Every step is idempotent, so a failed run can simply run again (the unit # reruns at the next boot while firstboot.conf exists). The log is @@ -48,6 +52,12 @@ # WIFI_SSID optional; WIFI_PSK with it (none for an open network) # CREDENTIAL pin or password: how the lock screen asks (default pin) # FULL_NAME, EMAIL optional; git identity, as Omarchy's installer asks +# FINGERPRINT yes or no: yes records the installer's acknowledgement of +# fingerprint's secure-storage write (typing the codename +# after its warning). Missing (an older installer) is no, +# never consent +# ACK_DATE the acknowledgement's date, YYYY-MM-DD (UTC); required +# with FINGERPRINT=yes set -euo pipefail # Tests run the whole thing against a scratch root and fake commands. @@ -103,7 +113,7 @@ parse() { [[ $value != *[$'\x01'-$'\x1f\x7f']* ]] || die "$file:$n: $key has control characters" case $key in SSH_KEY) SSH_KEYS+=("$value") ;; - USERNAME|PASSWORD_HASH|HOSTNAME|TIMEZONE|WIFI_SSID|WIFI_PSK|CREDENTIAL|FULL_NAME|EMAIL) + USERNAME|PASSWORD_HASH|HOSTNAME|TIMEZONE|WIFI_SSID|WIFI_PSK|CREDENTIAL|FULL_NAME|EMAIL|FINGERPRINT|ACK_DATE) [[ -z ${C[$key]+x} ]] || die "$file:$n: $key given twice" C[$key]=$value ;; *) die "$file:$n: unknown key $key" ;; @@ -150,6 +160,14 @@ validate() { [[ ${C[CREDENTIAL]} =~ ^(pin|password)$ ]] || die "CREDENTIAL must be pin or password" [[ ${C[FULL_NAME]:-} != *[:,]* ]] || die "FULL_NAME can't contain : or ," [[ -z ${C[EMAIL]:-} || ${C[EMAIL]} =~ ^[^[:space:]@]+@[^[:space:]@]+$ ]] || die "EMAIL '${C[EMAIL]}' is not an address" + # A missing FINGERPRINT is no: only an explicit acknowledgement is consent + C[FINGERPRINT]=${C[FINGERPRINT]:-no} + [[ ${C[FINGERPRINT]} =~ ^(yes|no)$ ]] || die "FINGERPRINT must be yes or no" + if [[ ${C[FINGERPRINT]} == yes ]]; then + [[ ${C[ACK_DATE]:-} =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ ]] || die "FINGERPRINT=yes needs ACK_DATE=YYYY-MM-DD (the acknowledgement's date)" + elif [[ -n ${C[ACK_DATE]+x} ]]; then + die "ACK_DATE without FINGERPRINT=yes" + fi } summary() { @@ -163,6 +181,11 @@ summary() { echo "wi-fi: none" fi [[ -n ${C[FULL_NAME]:-}${C[EMAIL]:-} ]] && echo "git: ${C[FULL_NAME]:-} <${C[EMAIL]:-}>" + if [[ ${C[FINGERPRINT]} == yes ]]; then + echo "fingerprint: on (secure-storage write acknowledged at install, ${C[ACK_DATE]})" + else + echo "fingerprint: off" + fi return 0 } @@ -190,8 +213,9 @@ U=${C[USERNAME]} WARNINGS=() FATAL=0 # step NAME FUNCTION: run one step, log its result, keep going on failure. -# Essential steps (the account, the password, SSH, the login) keep -# firstboot.conf in place when they fail, so the next boot tries again. +# Essential steps (the account, the password, SSH, the login, the +# fingerprint record) keep firstboot.conf in place when they fail, so the +# next boot tries again. step() { local name=$1 essential=$2 fn=$3 status echo "--- $name" @@ -458,6 +482,31 @@ s_user_setup() { return $failed } +# The owner acknowledged fingerprint's secure-storage write in the installer +# (FINGERPRINT=yes): record it where omamobile-fp-chroot looks before its +# first storage start, and enable the service. The unit stays inert until +# tools/phone-provision has pushed Google's files (its ConditionPathExists), +# then starts at the next boot. Nothing is started here. +s_fingerprint() { + [[ ${C[FINGERPRINT]} == yes ]] || { echo " off (no acknowledgement in firstboot.conf)"; return 0; } + mkdir -p "$ROOT/etc/omamobile" + { + echo "# Written by omamobile-firstboot from the installer's acknowledgement:" + echo "# the owner typed the codename after the warning that fingerprint's first" + echo "# start writes Trusty's secure storage. omamobile-fp-chroot requires it." + echo "CONSENT=yes" + echo "CONSENT_SOURCE=install-acknowledgement" + echo "CONSENT_DATE=${C[ACK_DATE]}" + } > "$ROOT/etc/omamobile/fingerprint.conf.new" + chmod 644 "$ROOT/etc/omamobile/fingerprint.conf.new" + mv -f "$ROOT/etc/omamobile/fingerprint.conf.new" "$ROOT/etc/omamobile/fingerprint.conf" + if [[ -f $ROOT/usr/lib/systemd/system/omamobile-fp.service ]]; then + systemctl enable omamobile-fp.service + else + echo " recorded; omamobile-fp.service isn't installed, so nothing to enable" + fi +} + step "pacman keyring" optional s_keyring step "hostname, time zone, locale" optional s_identity step "user ${U}" essential s_user @@ -468,6 +517,7 @@ step "services and firewall" essential s_services step "Wi-Fi" optional s_wifi step "login" essential s_login step "user setup" optional s_user_setup +step "fingerprint" essential s_fingerprint if ((FATAL)); then echo "=== firstboot incomplete: ${WARNINGS[*]}; firstboot.conf kept, the next boot tries again ===" diff --git a/packages/omamobile-firstboot/test/all b/packages/omamobile-firstboot/test/all index 403030cf7..789b32279 100755 --- a/packages/omamobile-firstboot/test/all +++ b/packages/omamobile-firstboot/test/all @@ -109,7 +109,17 @@ good | sed 's/^FULL_NAME=.*/FULL_NAME=a:b/' | refuse "a colon in the full name" { good; echo 'USERNAME=bob'; } | refuse "a key given twice" { good; echo 'not a line'; } | refuse "a line that isn't KEY=value" { good; printf 'EMAIL=a@b\x07c\n'; } | sed '/^EMAIL=alice/d' | refuse "a control character" +good | sed 's/^CREDENTIAL=.*/&\nFINGERPRINT=maybe/' | refuse "FINGERPRINT that is neither yes nor no" +good | sed 's/^CREDENTIAL=.*/&\nFINGERPRINT=yes/' | refuse "FINGERPRINT=yes without ACK_DATE" +good | sed 's/^CREDENTIAL=.*/&\nFINGERPRINT=yes\nACK_DATE=yesterday/' | refuse "an ACK_DATE that isn't a date" +good | sed 's/^CREDENTIAL=.*/&\nACK_DATE=2026-11-02/' | refuse "ACK_DATE without FINGERPRINT=yes" pass "--check refuses bad confs" +out=$(check "$t/good.conf") +grep -qx 'fingerprint: off' <<<"$out" || fail "no FINGERPRINT key means fingerprint off" +good | sed 's/^CREDENTIAL=.*/&\nFINGERPRINT=yes\nACK_DATE=2026-11-02/' > "$t/fp.conf" +out=$(check "$t/fp.conf") || fail "FINGERPRINT=yes with ACK_DATE passes: $out" +grep -q '^fingerprint: on .*2026-11-02' <<<"$out" || fail "--check reports the acknowledgement" +pass "--check: fingerprint only with an explicit, dated acknowledgement" # A value is data: a $(...) in it is never run mark=$t/ran @@ -209,6 +219,28 @@ grep -q '^clock-set' "$CALLS" && fail "no keyrings means no clock adjustment" grep -q '^pacman-key --populate' "$CALLS" || fail "key setup still runs without a floor" pass "missing keyrings leave the clock alone" +# Fingerprint: no key, no record and nothing enabled; the acknowledgement +# writes the consent record and enables the unit (inert until provisioned) +[[ ! -e $R/etc/omamobile/fingerprint.conf ]] || fail "no FINGERPRINT key: no consent record" +grep -q 'omamobile-fp' "$CALLS" && fail "no FINGERPRINT key: omamobile-fp isn't enabled" +mkdir -p "$R/usr/lib/systemd/system"; : > "$R/usr/lib/systemd/system/omamobile-fp.service" +: > "$CALLS" +good | sed 's/^CREDENTIAL=.*/&\nFINGERPRINT=no/' > "$R/etc/omamobile/firstboot.conf" +run || { cat "$t/run.out"; fail "FINGERPRINT=no runs"; } +[[ ! -e $R/etc/omamobile/fingerprint.conf ]] || fail "FINGERPRINT=no: no consent record" +grep -q 'omamobile-fp' "$CALLS" && fail "FINGERPRINT=no: omamobile-fp isn't enabled" +: > "$CALLS" +good | sed 's/^CREDENTIAL=.*/&\nFINGERPRINT=yes\nACK_DATE=2026-11-02/' > "$R/etc/omamobile/firstboot.conf" +run || { cat "$t/run.out"; fail "FINGERPRINT=yes runs"; } +printf '%s\n' CONSENT=yes CONSENT_SOURCE=install-acknowledgement CONSENT_DATE=2026-11-02 | + cmp -s - <(grep -v '^#' "$R/etc/omamobile/fingerprint.conf") || fail "the consent record" +[[ $(stat -c %a "$R/etc/omamobile/fingerprint.conf") == 644 ]] || fail "the consent record is readable (nothing secret in it)" +grep -qx 'systemctl enable omamobile-fp.service' "$CALLS" || fail "the acknowledgement enables omamobile-fp" +grep -q 'systemctl \(start\|restart\) omamobile-fp' "$CALLS" && fail "firstboot never starts omamobile-fp" +[[ ! -e $R/etc/omamobile/firstboot.conf ]] || fail "the conf is deleted after the run" +rm -f "$R/etc/omamobile/fingerprint.conf" "$R/usr/lib/systemd/system/omamobile-fp.service" +pass "fingerprint: the acknowledgement becomes the consent record and an enabled (not started) unit; none without it" + # An essential step failing keeps the conf (minus the Wi-Fi secret) for the next boot rm -f "$R/var/lib/omamobile/firstboot/user" sed -i '/^alice:/d' "$R/etc/passwd" diff --git a/packages/omamobile-firstboot/version b/packages/omamobile-firstboot/version index b1e80bb24..845639eef 100644 --- a/packages/omamobile-firstboot/version +++ b/packages/omamobile-firstboot/version @@ -1 +1 @@ -0.1.3 +0.1.4 From b8d98a6b578e086a103fd41b650a6782525421b5 Mon Sep 17 00:00:00 2001 From: Derek Ross Date: Mon, 2 Nov 2026 17:58:38 -0500 Subject: [PATCH 04/15] phone-provision: --fingerprint restores TD only with an explicit --restore-td --fingerprint restored the whole backup tree, Trusty's TD (data/vendor/ss) and the bridge's Gatekeeper secret included, from a backup of any age. TD's superblock lives in the RPMB, and every storageproxyd run moves it on, so a TD older than the RPMB mounts but its files can't be read: the 10-13/10-14 backups were three weeks older than the RPMB at the 2026-11-02 reinstall, and restoring them would have left a half-broken store. By default --fingerprint now copies only the safe pieces, mfg_data.img and the read-only persist:/ss copy (and the runner makes both itself on a new install). --restore-td adds TD and the secret, states the rule that no storageproxyd may have run between the backup and the restore, and refuses to replace a TD already on the phone without --force. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BeEcdVeSfyLCbijF8XQF1d --- tests/phone-provision | 32 +++++++++++++++++---- tools/phone-provision | 65 ++++++++++++++++++++++++++++++++----------- 2 files changed, 75 insertions(+), 22 deletions(-) diff --git a/tests/phone-provision b/tests/phone-provision index d13a88a63..585abc9df 100755 --- a/tests/phone-provision +++ b/tests/phone-provision @@ -49,8 +49,9 @@ tar -C "$S" -cf "$B/phone-config.tar" var/lib/omandroid-vendor/modem/props.conf etc/NetworkManager/system-connections home/omandroid/.config/omandroid home/omandroid/.config/omarchy/shell.json (cd "$B" && sha256sum phone-config.tar > phone-config.tar.sha256) F=$t/fp/omandroid-fp -mkdir -p "$F/persist-ss" "$F/data/vendor/omandroid-fp" +mkdir -p "$F/persist-ss" "$F/data/vendor/omandroid-fp" "$F/data/vendor/ss" echo 'secure storage' > "$F/persist-ss/0" +echo 'tamper-detect' > "$F/data/vendor/ss/0" echo 'calibration' > "$F/mfg_data.img" echo 'secret' > "$F/data/vendor/omandroid-fp/secret" tar -C "$t/fp" --numeric-owner --owner=0 --group=0 -cf "$B/var-lib-omandroid-fp.tar" omandroid-fp/mfg_data.img omandroid-fp/data @@ -75,21 +76,31 @@ for line in \ "etc/NetworkManager/system-connections/test.nmconnection -> /etc/NetworkManager/system-connections/test.nmconnection" \ "home/omandroid/.config/omandroid/home.json -> /home/alice/.config/omamobile/home.json" \ "home/omandroid/.config/omandroid/widgets -> /home/alice/.config/omamobile/widgets" \ - "/var/lib/omandroid-fp/data/vendor/omandroid-fp/secret -> /var/lib/omamobile-fp/data/vendor/omamobile-fp/secret" \ + "/var/lib/omandroid-fp/mfg_data.img -> /var/lib/omamobile-fp/mfg_data.img" \ + "/var/lib/omandroid-fp/persist-ss/0 -> /var/lib/omamobile-fp/persist-ss/0" \ "would stop omamobile-fp.service"; do grep -qF -- "$line" <<<"$out" || { echo "$out"; fail "maps: $line"; } done grep -q 'pacnew' <<<"$out" && fail "never restores .pacnew files" -grep -q 'first storageproxyd start' <<<"$out" || fail "warns that the first storageproxyd start needs the human's go" +grep -q 'never starts omamobile-fp' <<<"$out" || fail "says it never starts the fingerprint service" +grep -q 'data/vendor' <<<"$out" && fail "without --restore-td, no TD or Gatekeeper secret is restored" +out=$(PHONE_SSH=$t/no-ssh tools/phone-provision --dry-run --skip-extract --backup "$B" --work "$t/work" \ + --user alice --fingerprint --restore-td 2>&1) || { echo "$out"; fail "the --restore-td dry run succeeds"; } +grep -qF "/var/lib/omandroid-fp/data/vendor/omandroid-fp/secret -> /var/lib/omamobile-fp/data/vendor/omamobile-fp/secret" <<<"$out" || + fail "--restore-td restores the Gatekeeper secret" +grep -qF "/var/lib/omandroid-fp/data/vendor/ss/0 -> /var/lib/omamobile-fp/data/vendor/ss/0" <<<"$out" || fail "--restore-td restores TD" +grep -q 'no storageproxyd ran' <<<"$out" || fail "--restore-td states the no-run-in-between rule" +out=$(PHONE_SSH=$t/no-ssh tools/phone-provision --dry-run --skip-extract --backup "$B" --work "$t/work" --restore-td 2>&1) && + fail "--restore-td without --fingerprint is refused" [[ -z $(ls -A "$t/work") ]] || fail "the staging (per-phone data) is removed" -pass "dry run: old paths mapped to new names and the user's home, phone untouched, fingerprint warning" +pass "dry run: old paths mapped to new names and the user's home, phone untouched; fingerprint: calibration and persist:/ss only, TD only with --restore-td" # Raven's run does none of cheetah's backup or fingerprint steps: each of # their options is refused before anything runs, not ignored. The fake # ssh records any call, so a call made before the refusal is caught even # if the tool ignores its failure : > "$t/factory.zip" -for o in --fingerprint --import-home --restore-config --restore-wifi --with-waves --force "--backup $t"; do +for o in --fingerprint "--fingerprint --restore-td" --import-home --restore-config --restore-wifi --with-waves --force "--backup $t"; do # shellcheck disable=SC2086 # the --backup case is two words on purpose if out=$(PHONE_SSH=$t/no-ssh tools/phone-provision -d raven --dry-run --work "$t/work" $o "$t/factory.zip" 2>&1); then fail "-d raven refuses $o" @@ -279,7 +290,8 @@ on 'test ! -e /etc/omandroid && test ! -e /var/lib/omandroid-vendor && test ! -e on 'grep -q omamobile.home /home/alice/.config/omamobile/home.json && grep -q qs.Omamobile /home/alice/.config/omamobile/widgets/my.test-widget/Widget.qml' || fail "ids in the imported files are renamed" [[ $(on 'stat -c %u:%g /var/lib/omamobile-fp/persist-ss/0') == 1000:1000 ]] || fail "the fingerprint secure storage keeps its Android owner" -[[ $(on 'stat -c %u:%g /var/lib/omamobile-fp/data/vendor/omamobile-fp/secret') == 0:0 ]] || fail "the fingerprint secret stays root's" +on 'test ! -e /var/lib/omamobile-fp/data/vendor/omamobile-fp/secret && test ! -e /var/lib/omamobile-fp/data/vendor/ss/0' || + fail "without --restore-td, neither TD nor the Gatekeeper secret is restored" [[ $(on 'stat -c %a /var/lib/omamobile-fp') == 700 ]] || fail "the fingerprint state is private" pass "a real run: new names, root-owned system files, user-owned home files, Android owners for the fingerprint state" @@ -290,6 +302,14 @@ prov --fingerprint && fail "differing fingerprint state is never replaced withou grep -q -- '--force' "$t/out" || fail "says how to replace it" [[ $(on 'cat /var/lib/omamobile-fp/persist-ss/0') == enrolled-since ]] || fail "the phone's newer state is untouched" pass "differing fingerprint state is kept unless --force" +on 'echo secure storage > /var/lib/omamobile-fp/persist-ss/0' +prov --fingerprint --restore-td || { cat "$t/out"; fail "--restore-td runs"; } +[[ $(on 'stat -c %u:%g /var/lib/omamobile-fp/data/vendor/omamobile-fp/secret') == 0:0 ]] || fail "the fingerprint secret stays root's" +[[ $(on 'cat /var/lib/omamobile-fp/data/vendor/ss/0') == tamper-detect ]] || fail "--restore-td restores TD" +on 'echo newer > /var/lib/omamobile-fp/data/vendor/ss/0' +prov --fingerprint --restore-td && fail "a TD already on the phone is never replaced without --force" +[[ $(on 'cat /var/lib/omamobile-fp/data/vendor/ss/0') == newer ]] || fail "the phone's TD is untouched" +pass "--restore-td restores TD and the secret, and never over a TD already there without --force" # A first install against the stand-in phone: the board id from a stand-in # bootconfig (PHONE_BOOTCONFIG), the NV checksums from the stand-in backup. diff --git a/tools/phone-provision b/tools/phone-provision index 0583b10e3..df248d76a 100755 --- a/tools/phone-provision +++ b/tools/phone-provision @@ -30,11 +30,20 @@ # --restore-wifi saved NetworkManager connections # --import-home home screens, quick settings and widgets into the user's # ~/.config/omamobile (ids renamed omandroid -> omamobile) -# --fingerprint the fingerprint state (Trusty secure storage, factory -# calibration, enrolment) -> /var/lib/omamobile-fp, with the -# fingerprint service stopped. It never starts the service: -# the first storageproxyd start needs the human's go -# (FINGERPRINT-PLAN F4) +# --fingerprint the safe part of the fingerprint state: the factory +# calibration copy (mfg_data.img) and the read-only copy of +# persist:/ss (persist-ss/) -> /var/lib/omamobile-fp, with +# the fingerprint service stopped. It never starts the +# service. Not needed on a new install: the runner makes +# both copies itself from the partitions at its first start +# (FINGERPRINT-PLAN F19) +# --restore-td with --fingerprint: also the backup's TD (Trusty's +# tamper-detect store, data/vendor/ss) and the bridge's +# Gatekeeper secret, i.e. the enrolled fingers. Only valid +# if no storageproxyd ran on the phone between taking the +# backup and now: Trusty's RPMB anchors TD, so an older TD +# mounts but its files can't be read (FINGERPRINT-PLAN F19, +# the 2026-11-02 reinstall). Never restore an old one # A first install (cheetah with no phone-config.tar in the backup directory; # nothing here makes one, only the backup taken before the rename has it, so # a later reinstall counts too) has no backup to restore from, so @@ -60,6 +69,7 @@ # --work DIR local staging (default ~/.cache/omamobile-provision; it holds # Google's files and per-phone data, removed afterwards unless --keep) # --force replace fingerprint state that differs from the backup +# (with --restore-td, also a TD already on the phone) # --dry-run stage locally and print every extraction and push; touch # nothing on the phone # -d DEV cheetah (default) or raven. Raven (device/raven): the @@ -90,7 +100,7 @@ backup=$HOME/android/reference/phone-backup-20261013 work=${XDG_CACHE_HOME:-$HOME/.cache}/omamobile-provision getprop=$HOME/android/reference/raven-stock/getprop.txt nv_backup="" -dry=0 skip_extract=0 fingerprint=0 import_home=0 restore_config=0 restore_wifi=0 waves=0 keep=0 force=0 backup_given=0 +dry=0 skip_extract=0 fingerprint=0 restore_td=0 import_home=0 restore_config=0 restore_wifi=0 waves=0 keep=0 force=0 backup_given=0 user="" factory="" device=cheetah PHONE_SSH=${PHONE_SSH:-$ROOT/tools/phone-ssh} bootconfig=${PHONE_BOOTCONFIG:-/proc/bootconfig} @@ -99,6 +109,7 @@ while (($#)); do --dry-run) dry=1 ;; --skip-extract) skip_extract=1 ;; --fingerprint) fingerprint=1 ;; + --restore-td) restore_td=1 ;; --import-home) import_home=1 ;; --restore-config) restore_config=1 ;; --restore-wifi) restore_wifi=1 ;; @@ -119,6 +130,7 @@ while (($#)); do done ((skip_extract)) || [[ -n $factory ]] || die "give the factory image (FACTORY.zip), or --skip-extract" [[ -z $factory || -f $factory ]] || die "no $factory" +((restore_td == 0 || fingerprint)) || die "--restore-td goes with --fingerprint" [[ -n $factory ]] && factory=$(readlink -f "$factory") [[ $device == cheetah || $device == raven ]] || die "unknown device $device (cheetah or raven)" [[ $device == cheetah ]] || ((skip_extract == 0)) || die "-d $device needs the factory image" @@ -127,6 +139,7 @@ done if [[ $device == raven ]]; then unsupported=() ((fingerprint)) && unsupported+=(--fingerprint) + ((restore_td)) && unsupported+=(--restore-td) ((import_home)) && unsupported+=(--import-home) ((restore_config)) && unsupported+=(--restore-config) ((restore_wifi)) && unsupported+=(--restore-wifi) @@ -185,6 +198,7 @@ if [[ $device == cheetah && ! -f $backup/phone-config.tar ]]; then first_install=1 unsupported=() ((fingerprint)) && unsupported+=(--fingerprint) + ((restore_td)) && unsupported+=(--restore-td) ((import_home)) && unsupported+=(--import-home) ((restore_config)) && unsupported+=(--restore-config) ((restore_wifi)) && unsupported+=(--restore-wifi) @@ -490,18 +504,26 @@ fi if ((fingerprint)); then say "Fingerprint state" cat <<'WARN' - !! The fingerprint state is Trusty's secure storage for this phone. This - !! tool only copies it to /var/lib/omamobile-fp with the service stopped; - !! it never starts omamobile-fp. The first storageproxyd start on it writes - !! the phone's RPMB and is irreversible: it needs the human's explicit go - !! (device/cheetah/FINGERPRINT-PLAN.md F4). + !! This copies the fingerprint state to /var/lib/omamobile-fp with the + !! service stopped; it never starts omamobile-fp. Without --restore-td it + !! copies only the factory calibration copy and the read-only copy of + !! persist:/ss, never Trusty's TD or the enrolled fingers: a TD older than + !! the phone's RPMB can't be read (device/cheetah/FINGERPRINT-PLAN.md F19). WARN + if ((restore_td)); then + cat <<'WARN' + !! --restore-td: the backup's TD and Gatekeeper secret too. Only valid if + !! no storageproxyd ran on this phone since the backup was taken. +WARN + fi mkdir -p "$W/fp" tar -C "$W/fp" -xf "$fp_tar" --no-same-owner [[ -d $W/fp/omandroid-fp ]] || die "$fp_tar has no omandroid-fp/" # Ownership is Android's (storageproxyd runs as AID_SYSTEM, 1000), so this # one tree keeps the backup's numeric owners, renamed paths and all. - fp_list=$(tar -tf "$fp_tar" | sed 's|^omandroid-fp/||' | grep . || true) + # Without --restore-td only mfg_data.img and persist-ss/ are restored + fp_keep() { ((restore_td)) && return 0; [[ $1 == mfg_data.img || $1 == persist-ss || $1 == persist-ss/* ]]; } + fp_list=$(tar -tf "$fp_tar" | sed 's|^omandroid-fp/||; s|/$||' | grep . | while read -r f; do fp_keep "$f" && echo "$f"; done || true) while read -r f; do note "/var/lib/omandroid-fp/$f -> /var/lib/omamobile-fp/$(map_path "$f")"; done <<<"$fp_list" if ((dry)); then note "would stop omamobile-fp.service, then restore $(wc -l <<<"$fp_list") entries to /var/lib/omamobile-fp" @@ -514,25 +536,36 @@ WARN die "/var/lib/omamobile-fp already holds different secure storage: not replacing it (--force)" fi fi + if ((restore_td && force == 0)) && phone 'test -e /var/lib/omamobile-fp/data/vendor/ss/0'; then + die "/var/lib/omamobile-fp already holds a TD (storageproxyd has run here): not replacing it with the backup's (--force, and only if no storageproxyd ran since the backup)" + fi phone 'systemctl stop omamobile-fp.service 2>/dev/null; systemctl is-active --quiet omamobile-fp.service && exit 1; true' || die "omamobile-fp.service won't stop" # Rename the inner directory too, then stream with numeric owners kept - python3 -I - "$fp_tar" "$W/fp.tar" <<'PY' + python3 -I - "$fp_tar" "$W/fp.tar" "$restore_td" <<'PY' import sys, tarfile -src, dst = sys.argv[1], sys.argv[2] +src, dst, restore_td = sys.argv[1], sys.argv[2], sys.argv[3] == "1" +def keep(name): + return restore_td or name in (".", "mfg_data.img", "persist-ss") or name.startswith("persist-ss/") with tarfile.open(src) as i, tarfile.open(dst, "w") as o: for m in i.getmembers(): name = m.name if not name.startswith("omandroid-fp"): sys.exit(f"unexpected member {name}") - name = name[len("omandroid-fp"):].lstrip("/") or "." + name = name[len("omandroid-fp"):].strip("/") or "." + if not keep(name): + continue m.name = name.replace("omandroid", "omamobile") o.addfile(m, i.extractfile(m) if m.isfile() else None) PY phone 'set -e; mkdir -p /var/lib/omamobile-fp; tar -C /var/lib/omamobile-fp -xpf - --numeric-owner --same-owner' < "$W/fp.tar" phone 'chmod 0700 /var/lib/omamobile-fp; ls -ln /var/lib/omamobile-fp/persist-ss' note "restored; omamobile-fp.service stays stopped" - DID+=("restored the fingerprint state (service stopped, not started)") + if ((restore_td)); then + DID+=("restored the fingerprint state with TD and the enrolled fingers (service stopped, not started)") + else + DID+=("restored the fingerprint calibration and persist:/ss copies, not TD (service stopped, not started)") + fi fi fi From 67c3083aa6b10faf29efe018b819a03b96193241 Mon Sep 17 00:00:00 2001 From: Derek Ross Date: Mon, 2 Nov 2026 18:00:10 -0500 Subject: [PATCH 05/15] omamobile-shell 0.2.85: onboarding offers "Add a fingerprint" after the PIN With fingerprint on by default for new installs, setup should offer it. After the PIN step, when the sensor is ready (fprintd lists the device through omamobile-fp-enroll) and this user has no finger, onboarding asks once: "Add a fingerprint" opens the fingerprint screen's enrollment (the LHBM circle and polkit's PIN prompt), "Skip" says where to add one later (Setup > Security > Fingerprint). On a new install the sensor is ready only after tools/phone-provision and its restart, so setup then says it comes later, and the first login after it is ready sends one notification instead. Never before a PIN, never with a finger enrolled, never twice. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BeEcdVeSfyLCbijF8XQF1d --- .../omamobile-shell/bin/omamobile-onboarding | 90 +++++++++++++++++-- packages/omamobile-shell/test/all | 2 + .../test/onboarding-fingerprint.sh | 70 +++++++++++++++ packages/omamobile-shell/version | 2 +- 4 files changed, 156 insertions(+), 8 deletions(-) create mode 100644 packages/omamobile-shell/test/onboarding-fingerprint.sh diff --git a/packages/omamobile-shell/bin/omamobile-onboarding b/packages/omamobile-shell/bin/omamobile-onboarding index 419b6003a..51b0039c1 100644 --- a/packages/omamobile-shell/bin/omamobile-onboarding +++ b/packages/omamobile-shell/bin/omamobile-onboarding @@ -3,15 +3,24 @@ # First-run setup for a phone, the part Omarchy's installer asks on a computer: # your name and email (git identity and XCompose, through Omarchy's own # install/user/git.sh and xcompose.sh), then a PIN or password if there isn't -# one (omamobile-set-pin asks which). Then Omarchy's own invitation to pick a -# default AI agent (Setup > Default Agent): Omarchy shows it after the first -# update, a phone at first login. +# one (omamobile-set-pin asks which), then a fingerprint once the PIN exists +# and the sensor is ready (the fingerprint screen, omamobile.fingerprint). +# Then Omarchy's own invitation to pick a default AI agent (Setup > Default +# Agent): Omarchy shows it after the first update, a phone at first login. # -# omamobile-onboarding open a terminal and run it -# omamobile-onboarding --nudge at login: if anything is missing, say so +# omamobile-onboarding open a terminal and run it +# omamobile-onboarding --nudge at login: if anything is missing, say so +# omamobile-onboarding --fingerprint open the fingerprint screen's enrollment +# +# Fingerprint is offered once (setup, or the first login after the sensor +# is ready, which on a new install is after tools/phone-provision and its +# restart), never again after an answer: Setup > Security > Fingerprint +# stays the place to add or remove fingers. set -u omarchy_path=${OMARCHY_PATH:-/usr/share/omarchy} +fp_runner=${OMAMOBILE_FP_RUNNER:-/usr/lib/omamobile-fp/omamobile-fp-chroot} +fp_offered=${XDG_STATE_HOME:-$HOME/.local/state}/omamobile/fingerprint-offered has_identity() { [[ -n $(git config --global user.name) && -n $(git config --global user.email) ]] @@ -27,10 +36,73 @@ invite_agent() { [[ -f $hook ]] && bash "$hook" || true } +# This user's enrolled fingers, through fprintd, or nothing when the sensor +# isn't ready (no fingerprint stack, the service not running yet, no device). +fp_count() { + [[ -x $fp_runner ]] || return 0 + timeout 15 omamobile-fp-enroll list 2>/dev/null | python3 -c ' +import json, sys +for line in sys.stdin: + try: + e = json.loads(line) + except ValueError: + continue + if e.get("event") == "fingers" and e.get("device"): + print(len(e.get("fingers") or [])) + break +' 2>/dev/null || true +} + +# Offer a fingerprint when the sensor is ready and none is enrolled, once. +fp_wanted() { + [[ -x $fp_runner && ! -e $fp_offered ]] && has_pin && [[ $(fp_count) == 0 ]] +} + +fp_mark_offered() { + mkdir -p "${fp_offered%/*}" && date -Is > "$fp_offered" 2>/dev/null || true +} + +fp_enroll() { + omarchy-shell shell summon omamobile.fingerprint '{"page":"enroll"}' +} + +offer_fingerprint() { + [[ -x $fp_runner ]] || return 0 + if ! has_pin; then + return 0 + fi + local n + n=$(fp_count) + if [[ -z $n ]]; then + if systemctl is-enabled --quiet omamobile-fp.service 2>/dev/null; then + echo + echo "Fingerprint unlock will be ready once your phone's firmware is added and it restarts. The phone offers it then." + fi + return 0 + fi + ((n == 0)) || return 0 + [[ ! -e $fp_offered ]] || return 0 + echo + if gum confirm "Add a fingerprint? It unlocks the phone alongside your PIN or password." \ + --affirmative "Add a fingerprint" --negative "Skip"; then + fp_enroll || echo "Open Setup > Security > Fingerprint to add one." + else + echo "Skipped. Add one any time in Setup > Security > Fingerprint." + fi + fp_mark_offered +} + case "${1:-}" in --nudge) # one nudge at a time: the agent waits until the phone itself is set up if has_identity && has_pin; then + if fp_wanted; then + fp_mark_offered + omarchy-notification-send "Add a fingerprint" \ + "Unlock your phone with a finger as well as your PIN. Tap to add one." \ + --exec "omamobile-onboarding --fingerprint" + exit 0 + fi invite_agent exit 0 fi @@ -38,8 +110,11 @@ case "${1:-}" in "Add your name and email, and a PIN or password to lock it. Tap to start." \ --exec omamobile-onboarding ;; + --fingerprint) + fp_enroll + ;; --inner) - echo "Welcome to Omarchy Mobile. Two quick steps." + echo "Welcome to Omarchy Mobile. A few quick steps." echo name=$(gum input --header "Your name" --placeholder "Ada Lovelace" --value "$(git config --global user.name)") email=$(gum input --header "Your email" --placeholder "ada@example.com" --value "$(git config --global user.email)") @@ -54,13 +129,14 @@ case "${1:-}" in else omamobile-set-pin --inner fi + offer_fingerprint invite_agent ;; "") exec omarchy-launch-floating-terminal-with-presentation "omamobile-onboarding --inner" ;; *) - echo "Usage: omamobile-onboarding [--nudge]" >&2 + echo "Usage: omamobile-onboarding [--nudge | --fingerprint]" >&2 exit 1 ;; esac diff --git a/packages/omamobile-shell/test/all b/packages/omamobile-shell/test/all index c4f5699bb..260ace2cf 100755 --- a/packages/omamobile-shell/test/all +++ b/packages/omamobile-shell/test/all @@ -981,6 +981,8 @@ else pass "widget crash guard: same-boot death held back, one retry after a system going down, clean run and quit clear" fi bash test/osk-guard.sh || fail "omamobile-osk-guard" +bash -n bin/omamobile-onboarding || fail "omamobile-onboarding parses" +bash test/onboarding-fingerprint.sh || fail "omamobile-onboarding's fingerprint offer" bash -n bin/omamobile-sleepd || fail "omamobile-sleepd parses" bash test/sleepd.sh || fail "omamobile-sleepd" python3 -B -c 'import ast,sys; ast.parse(open(sys.argv[1]).read())' bin/omamobile-weather || fail "omamobile-weather parses" diff --git a/packages/omamobile-shell/test/onboarding-fingerprint.sh b/packages/omamobile-shell/test/onboarding-fingerprint.sh new file mode 100644 index 000000000..e76e08d59 --- /dev/null +++ b/packages/omamobile-shell/test/onboarding-fingerprint.sh @@ -0,0 +1,70 @@ +#!/bin/bash +# SPDX-License-Identifier: MIT +# omamobile-onboarding's fingerprint offer against fakes (gum, fprintd's +# listing through omamobile-fp-enroll, the shell, notifications): offered +# after the PIN when the sensor is ready and nothing is enrolled, once; +# never before a PIN, never with a finger enrolled, and a not-ready sensor +# gets a "later" line in setup and silence at login (then the next login +# offers it). +set -euo pipefail +cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." +fail() { printf 'not ok - %s\n' "$1" >&2; exit 1; } +pass() { printf 'ok - %s\n' "$1"; } +t=$(mktemp -d); trap 'rm -rf "$t"' EXIT +F=$t/fakes; mkdir -p "$F" "$t/home" +fake() { printf '#!/bin/bash\n%s\n' "$2" >"$F/$1"; chmod +x "$F/$1"; } +: >"$t/runner"; chmod +x "$t/runner" +fake git 'echo set' +# an empty password is accepted (no PIN) until $T/pin exists +fake unix_chkpwd '[[ ! -e $T/pin ]]' +fake gum 'case $1 in input) echo ;; confirm) echo "confirm $2" >>"$T/log"; [[ -e $T/yes ]] ;; esac' +fake omamobile-set-pin 'case $1 in --type) echo PIN ;; --inner) touch "$T/pin" ;; esac' +fake omamobile-fp-enroll '[[ -e $T/listing ]] && cat "$T/listing"; true' +fake omarchy-shell 'echo "shell $*" >>"$T/log"' +fake omarchy-notification-send 'echo "notify $*" >>"$T/log"' +fake systemctl '[[ $* == "is-enabled --quiet omamobile-fp.service" && -e $T/enabled ]]' +fake timeout 'shift; "$@"' +ob() { + env -u XDG_STATE_HOME T="$t" HOME="$t/home" USER=alice OMARCHY_PATH="$t/none" OMAMOBILE_FP_RUNNER="$t/runner" \ + PATH="$F:/usr/bin:/bin" bash bin/omamobile-onboarding "$@" >"$t/out" 2>&1 +} +reset() { rm -f "$t/pin" "$t/yes" "$t/listing" "$t/enabled" "$t/log"; rm -rf "$t/home/.local"; : >"$t/log"; } +ready() { printf '{"event": "fingers", "fingers": [%s], "stages": 12, "device": "Omarchy Mobile UDFPS"}\n' "${1:-}" >"$t/listing"; } + +# Setup: the PIN is set, then the fingerprint is offered and taken +reset; ready; touch "$t/yes" +ob --inner || { cat "$t/out"; fail "setup runs"; } +grep -c '^confirm Add a fingerprint' "$t/log" >/dev/null || fail "the fingerprint is offered after the PIN" +grep -c 'shell shell summon omamobile.fingerprint {"page":"enroll"}' "$t/log" >/dev/null || fail "yes opens the enrollment screen" +[[ -e $t/home/.local/state/omamobile/fingerprint-offered ]] || fail "the offer is remembered" +ob --inner; [[ $(grep -c '^confirm' "$t/log") == 1 ]] || fail "offered once only" +pass "setup: after the PIN, a ready sensor with no finger gets one offer" + +reset; ready +ob --inner +grep -c 'Skipped' "$t/out" >/dev/null || fail "skip says where to add one later" +grep -c 'summon' "$t/log" >/dev/null && fail "skip opens nothing" +reset; ready '"right-index-finger"' +ob --inner; grep -c 'confirm' "$t/log" >/dev/null && fail "a finger already enrolled: no offer" +reset; touch "$t/enabled" +ob --inner; grep -c 'confirm' "$t/log" >/dev/null && fail "a sensor not ready: no offer" +grep -c 'ready once your phone' "$t/out" >/dev/null || fail "a sensor not ready yet: setup says it comes later" +[[ ! -e $t/home/.local/state/omamobile/fingerprint-offered ]] || fail "not ready: the offer waits for a later login" +reset; ready; rm -f "$t/runner" +ob --inner; grep -c 'confirm' "$t/log" >/dev/null && fail "no fingerprint stack: no offer" +: >"$t/runner"; chmod +x "$t/runner" +pass "setup: no offer when skipped, already enrolled, not ready or not installed" + +# Login: no PIN yet means the setup nudge, not the fingerprint +reset; ready +ob --nudge; grep -c 'notify.*Finish setting up' "$t/log" >/dev/null || fail "no PIN: the setup nudge" +grep -c 'Add a fingerprint' "$t/log" >/dev/null && fail "no fingerprint offer before a PIN" +# PIN set, sensor ready, nothing enrolled: one fingerprint notification +reset; ready; touch "$t/pin" +ob --nudge; grep -c '^notify Add a fingerprint.*--exec omamobile-onboarding --fingerprint' "$t/log" >/dev/null || fail "login offers the fingerprint" +: >"$t/log"; ob --nudge; grep -c 'notify' "$t/log" >/dev/null && fail "the login offer comes once" +# not ready at login: silent, and the next login offers it +reset; touch "$t/pin" +ob --nudge; grep -c 'notify' "$t/log" >/dev/null && fail "not ready at login: no notification" +ready; ob --nudge; grep -c '^notify Add a fingerprint.*--exec omamobile-onboarding --fingerprint' "$t/log" >/dev/null || fail "the next login offers it once ready" +pass "login: one fingerprint notification once the PIN exists and the sensor is ready" diff --git a/packages/omamobile-shell/version b/packages/omamobile-shell/version index af8feae39..ef61b8ebe 100644 --- a/packages/omamobile-shell/version +++ b/packages/omamobile-shell/version @@ -1 +1 @@ -0.2.82 +0.2.85 From 6d8501fb2d7f849c46aa93e2c08fd9d9297fbd80 Mon Sep 17 00:00:00 2001 From: Derek Ross Date: Mon, 2 Nov 2026 18:01:37 -0500 Subject: [PATCH 06/15] FINGERPRINT-PLAN: F19, the reinstall's run, the storage crash, and fingerprint on by default F19 records the 2026-11-02 reinstall and turns it into the runbook: why an empty TD is safe (Trusty clears it, like a factory reset), why an old TD isn't (the RPMB anchor moved on), and why TDP must be served from a fresh read-only copy of persist:/ss/0. Corrected after the run: F19.4 to the enrollment is one storageproxyd session (one start of the service, not the stage-by-stage starts), a stop condition makes any proxy stop or restart in the boot mean a reboot before enrolling, and the first enrollment should show "write initial superblock". Results on 7.3.0-rc6-omamobile-g2219cc6cda77: F19.0-F19.3 passed (TDP copy e0e1990d, nsp 078a4f9c, mfg_data matching 10-13); F19.4 loaded tp, tdp and nsp and cleared td; the first enrollment, after two stage restarts, asserted Trusty's storage app and halted Trusty; after a reboot one continuous run enrolled right-index-finger and matched; TDP unchanged, radio partitions SAME. The rules section and status describe the default-on path and the install acknowledgement as consent; the fresh-install checks T1-T3 are listed as still to run. NOTES.md has the day's entry. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BeEcdVeSfyLCbijF8XQF1d --- device/cheetah/FINGERPRINT-PLAN.md | 233 ++++++++++++++++++++++++++++- device/cheetah/NOTES.md | 30 ++++ 2 files changed, 258 insertions(+), 5 deletions(-) diff --git a/device/cheetah/FINGERPRINT-PLAN.md b/device/cheetah/FINGERPRINT-PLAN.md index 053835c5f..a44c1d745 100644 --- a/device/cheetah/FINGERPRINT-PLAN.md +++ b/device/cheetah/FINGERPRINT-PLAN.md @@ -1,7 +1,18 @@ # Fingerprint plan (cheetah / gs201): fingerprint unlock on the lock screen -Status (2026-10-19): **works, opt-in.** F3-F9 (the HAL) and the fprintd +Status (2026-11-02): **on by default for new installs, from +omamobile-fingerprint 0.1.14 and omamobile-firstboot 0.1.4** (section 6, +F19). The installer's wipe warning names the secure-storage write, typing +the codename is the owner's consent, firstboot records it in +`/etc/omamobile/fingerprint.conf` and enables `omamobile-fp`, and the runner +makes the read-only copies of `mfg_data` and `persist:/ss` itself, refuses +storageproxyd without the consent record or the TDP copy, and runs one +storage proxy per boot. The reference phone was reinstalled on 2026-11-02 +and enrolled again by hand (F19 results, section 7). The fresh-install checks +(F19.T1-T3) haven't run yet. + +Earlier status (2026-10-19): **works, opt-in.** F3-F9 (the HAL) and the fprintd stages through F16b passed on the phone (section 7): the lock screen unlocks with a finger alongside the PIN pad or password, and enrollment runs from the shell. libfprint 1.94.100-1.6 keeps a @@ -159,10 +170,27 @@ surprises are in F6c (what the HAL waits on) and F7 (LHBM timing). ## 4. Rules for this subsystem - **Never write `persist` or the RPMB without the human's explicit say-so.** - The first `storageproxyd` run (F4) counts as an irreversible write: ask, - and record the answer here. Every later start of `omamobile-fp.service` or - `omamobile-fp-chroot start` also runs storageproxyd: after F4 that is - normal operation, before F4 it is F4. + The first `storageproxyd` run (F4) counts as an irreversible write. Since + 2026-11-02 the owner's recorded install-time acknowledgement counts as + that say-so on their phone: the installer's warning names the write, + typing the codename acknowledges it, and `/etc/omamobile/fingerprint.conf` + (`CONSENT=yes`, written by firstboot) records it. The runner refuses the + first storage start without that record. Anywhere else (a phone set up + by hand, an agent's runbook), ask, and record the answer here. Every later + start of `omamobile-fp.service` or `omamobile-fp-chroot start` also runs + storageproxyd: after the first run that is normal operation. +- `persist` is never written, and `mfg_data` neither: both are only read, + and the TDP copy stays read-only (decision A, section 5). A TDP copy that + changes, or a `persist:/ss/0` that no longer matches it, stops the runner + (F19). +- **One storage proxy per boot.** Trusty keeps each store's state until a + reboot; stopping and starting storageproxyd in the same boot before TD's + first commit crashed Trusty's storage app on 2026-11-02 (F19). Never stop + and start `omamobile-fp`, `omamobile-fp-stage` or any storageproxyd in one + boot: reboot. The runner refuses a second start, and the unit has no + `Restart=`. +- Never restore an old TD (`tools/phone-provision --restore-td`) unless no + storageproxyd ran between taking the backup and restoring it. - `persist` and `mfg_data` are only ever read (read-only mount, `dd` from the by-partlabel node). Never add them to the storage guard's `UFS_RW` allowlist without the human's decision (section 5). @@ -907,6 +935,196 @@ Then lock: no keyboard; PIN on the pad unlocks (and a wrong one fails); the finger unlocks; ABC shows the keyboard, 123 folds it. **Stop** on any wrong-PIN for a correct one: restore `/root/LockView.qml.pre-f16b`. +### F19: fingerprint after a reinstall, and on by default for new installs (2026-11-02) + +The reference phone was reinstalled on 2026-11-02: `userdata` wiped, the +RPMB kept. TD's file half went with `userdata`, and the RPMB still anchored +the last TD. Three facts decide the runbook: + +- **An empty TD is safe.** Trusty sees an empty TD file and clears it + ("fs td: clear requested, create empty"), writing a new TD superblock to + the RPMB, as every Android factory reset does. It costs the enrolled + fingers and Trusty Gatekeeper's failure records; TP (KeyMint, AVB), TDP, + `persist` and `mfg_data` are untouched. This is what F4 did on 10-13. +- **An old TD is not.** The 10-13/10-14 backups' TD is older than the RPMB + anchor (every storageproxyd run since moved it on), so it would mount and + then not read. So no TD restore: `tools/phone-provision --fingerprint` + now copies only `mfg_data.img` and `persist-ss/`, and TD only with + `--restore-td`, which is valid only if no storageproxyd ran since the + backup. +- **TDP must be served from a copy of `persist:/ss/0`.** An empty TDP gets + no clear (unlike TD); against stock's TDP anchor in the RPMB it reads as + corrupted but may stay writable, and a TA commit would then move the TDP + anchor past stock's real `persist:/ss/0` for good. Linux never wrote TDP: + `persist:/ss/0` hashed to `e0e1990d…` in the 10-12, 10-30 and 11-02 + persist backups and in both fingerprint backup tars. + +Variables: `B=~/android/reference/cheetah-nv-backup-20261102`. + +**F19.0 Backups match (read-only; risk none).** + +```sh +tools/phone-ssh 'for p in efs efs_backup modem_userdata persist modem_a modem_b; do + d=$(grep -lx "PARTNAME=$p" /sys/class/block/*/uevent | head -1 | cut -d/ -f5) + printf "%s %s.img\n" "$(sha256sum < /dev/$d | cut -d" " -f1)" "$p"; done' > logs/f19-partitions.sha256 +grep -E ' (efs|efs_backup|modem_userdata|persist|modem_a|modem_b)\.img$' "$B/SHA256SUMS" | sort -k2 | + diff - <(sort -k2 logs/f19-partitions.sha256) && echo SAME +``` + +Pass: `SAME`. **Stop** on any difference: take a fresh read-only backup and +find out why first. + +**F19.1 Nothing has run yet (read-only; risk none).** `uname -r`, the +package versions, `systemctl is-enabled omamobile-fp` (disabled), +`systemctl is-active omamobile-fp omamobile-fp-stage` (inactive), no +`storageproxyd`, no `/var/lib/omamobile-fp/data/vendor/ss/0`, the vendor +tree present (phone-provision ran), the sensor node `okay`. **Stop** if +storageproxyd already ran on this install: TD is already fresh, go to +F19.5. **Stop** if the vendor tree is missing: run `tools/phone-provision`. + +**F19.2 Trusty ports (read-only; risk low).** As F2: cloudripper, API 5, +`allow_cpu_offline` `N`, `apploader keymint gatekeeper` open. + +**F19.3 Read-only copies of `mfg_data` and `persist:/ss` (writes only +`userdata`; risk low).** `debugfs` reads without mounting, so no journal +replay (never plain `-o ro`). From omamobile-fingerprint 0.1.14 the runner +does exactly this at its first start (and records the hashes in +`/var/lib/omamobile-fp/provenance`); by hand: + +```sh +tools/phone-ssh 'set -e; part() { grep -lx "PARTNAME=$1" /sys/class/block/*/uevent | head -1 | cut -d/ -f5; } + P=$(part persist) M=$(part mfg_data); echo "persist ro=$(cat /sys/class/block/$P/ro) mfg_data ro=$(cat /sys/class/block/$M/ro)" + grep -c "^/dev/$P " /proc/mounts || true + install -d -m 0700 /var/lib/omamobile-fp /var/lib/omamobile-fp/persist-ss + dd if=/dev/$M of=/var/lib/omamobile-fp/mfg_data.img bs=1M status=none + cd /var/lib/omamobile-fp/persist-ss && debugfs -R "dump -p /ss/0 0" /dev/$P && debugfs -R "dump -p /ss/nsp nsp" /dev/$P + sha256sum /var/lib/omamobile-fp/persist-ss/0 /var/lib/omamobile-fp/persist-ss/nsp /var/lib/omamobile-fp/mfg_data.img | cut -c1-16' +``` + +Pass: both `ro=1`, `persist` not mounted; `persist-ss/0` `e0e1990d…`, `nsp` +`078a4f9c…` (stock's, 10-11), `mfg_data.img` equal to the laptop's 10-13 +copy. **Stop** on `ro=0` or any other `persist-ss/0` hash (stock's TDP +changed: don't start storage, ask). Rollback: `rm -rf /var/lib/omamobile-fp`. + +**F19.4 Secure storage, one proxy session from here to the enrollment +(IRREVERSIBLE: an RPMB write; the human's go first).** Trusty clears TD, +writing a new TD superblock to the RPMB. **Don't use the stage-by-stage +starts** (`start storage`, then `start hal`) here: Trusty keeps TD's +in-memory state (the pending "initial" superblock of the clear) for the +whole boot, and a storage proxy stopped and started before TD's first +commit is what crashed it (results below). One start of the service runs +F19.4-F19.7 in one session: + +```sh +# --- the irreversible step --- +tools/phone-ssh 'systemctl enable --now omamobile-fp' +tools/phone-ssh 'sleep 20; journalctl -u omamobile-fp -b --no-pager | tail -40; + grep -iE "fs (tp|td|tdp|nsp)|super|corrupt|probe|rpmb" /dev/trusty-log0 | tail -20' +``` + +Expect "secure storage ready" and Trusty's log: `tp` loaded, **`tdp` +loaded**, `nsp` loaded, `td` "clear requested, create empty". No MAC or +RPMB errors. **Stop at once** (reboot, don't restart the service) on +"Backing file probe failed", "corrupted", "bad block count", `tdp` not +loaded, or an RPMB authentication error, and take the logs to the +maintainer: a TDP inconsistent with the RPMB is the one case where going on +could break stock's persistent state. Rollback: none (the RPMB can't be +rolled back); reboot to drop the proxy. + +**F19.5 TA, keys, HAL in the same session (read-only checks; risk low).** + +```sh +tools/phone-ssh 'journalctl -u omamobile-fp -b --no-pager | grep -E "g7|\[fingerprint\]|\[keymint\]|\[gatekeeper\]|calibration|auth-token" | tail -30' +``` + +Expect "g7.app loaded", KeyMint and Gatekeeper up, "Initialization +successful", the sensor at (717, 2360) r 121, no "without factory +calibration", "auth-token key agreed" and "gatekeeper: enrolled" (a new +secret). **Stop** on a HAL crash: the unit then stays failed (no +`Restart=`); reboot, don't restart it. The general rule: Trusty keeps each +store's state for the whole boot; a proxy restart doesn't reset it, a +reboot does. + +**F19.6 Stop condition before enrolling.** If storageproxyd stopped or +restarted in this boot after F19.4 (any `stop`, a crash, a unit restart), +reboot first. From 0.1.14 the runner refuses a second start until a +reboot anyway. + +**F19.7 Enroll (announce first: the bright LHBM circle).** Setup > +Security > Fingerprint (polkit asks for the PIN), then +`fprintd-list `. Expect, at the first enrollment, in +`/dev/trusty-log0`: "write initial superblock before block N" and "write +initial superblock, version N -> N+1": the clear flushed by TD's first +commit in the same session. **Stop** on "Assert fail" or "Unclean exit from +critical app" (Trusty halts, and with it the AoC: no sound or sensors until +a reboot). Reboot, check that TD came up (Trusty clears it again by itself +at mount when the superblock is unusable), and enroll again. Lock and unlock +with the finger; the PIN still unlocks. + +**F19.8 After-checks (read-only).** After the enrollment, a few unlocks and +one reboot: `sha256sum /var/lib/omamobile-fp/persist-ss/0 | cut -c1-16` +still `e0e1990d…`, then F19.0 again (`SAME`). If TDP changed, record it: +going back to stock may then find TDP inconsistent. + +**F19.9 A backup that can restore (optional).** A TD backup is valid only +if no storageproxyd runs between taking and restoring it: take it right +before a wipe, with the service stopped (`systemctl stop omamobile-fp; tar +-C /var/lib -cf - omamobile-fp | …` into `~/android/reference/`, mode 600), +and restore it with `--restore-td`. Never restore an older one. + +#### F19 on a new install: what runs by itself (omamobile-fingerprint 0.1.14, omamobile-firstboot 0.1.4) + +1. `tools/install-phone` shows the warning with the fingerprint paragraph + before the codename; the typed codename is the acknowledgement, recorded + as `FINGERPRINT=yes` and `ACK_DATE` in `firstboot.conf`. +2. Firstboot writes `/etc/omamobile/fingerprint.conf` (`CONSENT=yes`, + `CONSENT_SOURCE=install-acknowledgement`, `CONSENT_DATE`) and enables + `omamobile-fp`. The unit is skipped (`ConditionPathExists`) until + `tools/phone-provision` has pushed Google's tree. +3. At the reboot after provisioning, the runner's preflight: consent present + (or this install's TD already exists), `persist` and `mfg_data` `ro=1` + and `persist` not mounted read-write, the F19.3 copies made and hashed + into `provenance`, the TDP copy and `persist:/ss/0` both still matching + the recorded hash, and no storageproxyd earlier in this boot. Any failure + refuses before storageproxyd and leaves the unit failed; the lock uses + the PIN. +4. One session: storage, the TA, KeyMint, Gatekeeper, the HAL, the bridge. + On stop, the bridge and the HAL go first and storageproxyd last. +5. Onboarding offers "Add a fingerprint" after the PIN once the sensor is + ready (or at the first login after it is), once. + +A divergent TDP refuses the start instead of warning. Once Linux (or a +stock boot after a slot A fallback) has written TDP, each further start +moves the RPMB anchor on from the copy stock would read, and only the +maintainer can judge what is safe then. The refusal keeps the phone's state +as it was found, and costs only fingerprint (the PIN unlocks). + +**Fresh-install checks before calling default-on done** (the test phone; +wipes are fine there): + +- **T1, a new install.** The release bundle with these packages and the new + installer. Before `phone-provision`: `systemctl is-enabled omamobile-fp` + enabled, the unit skipped by its condition, `/etc/omamobile/fingerprint.conf` + present. After provisioning and the reboot: the runner's log shows the + copies and the recorded hashes (`persist-ss/0` `e0e1990d…`), Trusty's log + as in F19.4, enrollment from onboarding with the "write initial superblock" + lines, and unlocking works. Then `systemctl restart omamobile-fp`: refused + with "reboot"; a reboot: it starts again. A day of use, three reboots and + sleep cycles: TDP still `e0e1990d…`, F19.0 `SAME`. Negative: with + `--no-fingerprint` the unit stays disabled and `omamobile-fp-chroot + preflight` refuses (no consent); with `persist-ss/0` removed by hand the + runner refuses storageproxyd. +- **T2, back to stock.** `fastboot --set-active=a`, recovery, "Factory data + reset"; set up Android with a PIN, enroll a finger, unlock with it, reboot + twice; make a TEE-backed key; `adb logcat -b all -d | grep -iE + "trusty|storage|tdp|corrupt|ss:"` and `adb shell dumpsys fingerprint`. + Pass: no storage errors, fingerprint and keystore work. Then a fresh NV + backup, and re-hash `persist:/ss/0` (did stock write TDP?). +- **T3, a reinstall after stock.** `tools/install-phone` again: the first + start shows the same clean log (TD cleared again), the new copies equal + `persist:/ss` as stock left it, and enrollment works. If T2 changed + `persist:/ss/0`, the new install's copy is the new hash: that is correct. + ## 7. Results | Step | Date | `uname -r` | Result | @@ -922,6 +1140,11 @@ wrong-PIN for a correct one: restore `/root/LockView.qml.pre-f16b`. | F7 | 2026-10-13 | `…-00402` | **Passed** (the human ran it): a bright circle over the sensor, timed out by itself. `allow_lhbm` resets at boot: package 0.1.2+ sets it with a modprobe option | | F8 | 2026-10-13 | `7.3.0-rc6-omamobile-push1-00405-g3bc8d8565645` | First tries: Gatekeeper enroll failed with `UNEXPECTED_NULL` (the bridge sent null arrays; fixed to empty arrays in 0.1.2); the HAL couldn't open `mfg_data` read-write (now a per-run scratch copy); `allow_lhbm` off after a reboot (no circle). A cancel the HAL never answers leaves the bridge stuck; restarting the service then fails (Trusty keeps the old storage proxy) until a reboot. **Passed**: about 17 good touches, `PROGRESS` 34 → 0, `ENROLLED`. `ACQUIRED 11` (immobile) when the finger isn't moved between touches | | F9 (HAL) | 2026-10-13 | `…-00405` | **Passed**: enrolled finger → `MATCH`; another finger → `NOMATCH`. fprintd next | +| F19.0-F19.3 | 2026-11-02 | `7.3.0-rc6-omamobile-g2219cc6cda77` | **Passed**: the six radio/persist partitions `SAME` as the 11-02 backup; Trusty ports open; copies made with `debugfs` (persist not mounted): `persist-ss/0` `e0e1990d…`, `nsp` `078a4f9c…`, `mfg_data.img` matching the 10-13 copy | +| F19.4 | 2026-11-02 | `…-g2219cc6cda77` | **Passed** (the human's go): `tp`, `tdp`, `nsp` loaded; `td` "clear requested, create empty"; no RPMB errors | +| F19.5-F19.7, first try | 2026-11-02 | `…-g2219cc6cda77` | **Trusty storage crash.** Run stage by stage (`start storage`, stop, `start hal`, stop, then the service), so storageproxyd was stopped twice between TD's clear and TD's first commit, once under a live g7 TA. At enrollment the first TD commit printed no "write initial superblock", and the next asserted in the storage app (`block_get_cleared_super`: a dirty superblock slot already pending), "Unclean exit from critical app", Trusty HALT. Trusty keeps a store's state across a proxy restart, and only a reboot resets it | +| F19.5-F19.7, after a reboot | 2026-11-02 | `…-g2219cc6cda77` | **Passed**: one continuous storageproxyd session from boot. Trusty cleared TD again by itself at mount, and the first commit flushed it ("write initial superblock before block 5", "version 0 -> 1"). `right-index-finger` enrolled at 17:15:25 and matched at 17:15:33 | +| F19.8 | 2026-11-02 | `…-g2219cc6cda77` | **Passed**: the TDP copy unchanged (`e0e1990d…`, mtime 2022-11-01); the radio partitions `SAME` | **F16b result (2026-10-13, phone LockView.qml 4c72b5be):** passed. The human confirmed: no keyboard over the lock until ABC, a correct PIN on the pad diff --git a/device/cheetah/NOTES.md b/device/cheetah/NOTES.md index a57ce2104..ae462f53b 100644 --- a/device/cheetah/NOTES.md +++ b/device/cheetah/NOTES.md @@ -2,6 +2,36 @@ Findings from real hardware, newest first. `BRINGUP-M1.md` is the research map written before first boot. +## 2026-11-02: fingerprint after the reinstall, a Trusty storage crash, and fingerprint on by default + +Kernel `7.3.0-rc6-omamobile-g2219cc6cda77`; Trusty "cloudripper". Details, +the runbook and every step: [FINGERPRINT-PLAN](FINGERPRINT-PLAN.md) F19. + +- **The reinstall's TD was not restored** [V]: the backups' TD (10-13, 10-14) + was older than the RPMB anchor, which every storageproxyd run moves on, + so it would have mounted and not read. Trusty cleared an empty TD instead + ("clear requested, create empty"), as at a factory reset. +- **Linux never wrote TDP** [V]: `persist:/ss/0` hashed `e0e1990d…` in the + 10-12, 10-30 and 11-02 persist backups, in both fingerprint backups and + in the fresh `debugfs` copy, and was unchanged after the enrollment. +- **A storage proxy restarted in the same boot crashed Trusty's storage + app** [V]: run stage by stage, storageproxyd was stopped twice between + TD's clear and TD's first commit (once under a live g7 TA). At + enrollment the storage app asserted in `block_get_cleared_super` (a + superblock slot already dirty) and Trusty halted. Trusty keeps each + store's in-memory state across a proxy restart; only a reboot resets it. + After a reboot, one continuous session enrolled `right-index-finger` + (17:15:25) and matched it (17:15:33), with the expected "write initial + superblock" lines. +- **Fingerprint is now on by default for new installs**, by the maintainer's + decision: the installer's warning names the secure-storage write and the + typed codename is the consent (firstboot records it in + `/etc/omamobile/fingerprint.conf`). The runner makes the read-only copies + itself, refuses storageproxyd without consent or the TDP copy or when TDP + changed, and runs one storage proxy per boot (no `Restart=`, a `/run` + marker, the proxy stopped last). The fresh-install checks T1-T3 are still + to run. + ## 2026-11-02: a kernel update through pacman, booted and rolled back Release kernel `7.3.0-rc6-omamobile-g2219cc6cda77` (tag `kernel-2026.11.01`), from the push1 build `7.3.0-rc6-omamobile-push1-g2219cc6cda77`; linux-omamobile `7.3.0rc6.r635.g2219cc6cda77-1`, omamobile-boot-update 0.1.0, device-cheetah 0.1.38 (#320). From 864c444188505c71469495514f5c248e4d670e9e Mon Sep 17 00:00:00 2001 From: Derek Ross Date: Mon, 2 Nov 2026 18:01:37 -0500 Subject: [PATCH 07/15] AGENTS.md: the install acknowledgement is the go for fingerprint's first storageproxyd run The maintainer decided on 2026-11-02 that the owner's recorded install-time acknowledgement (the installer's warning, the typed codename, firstboot's /etc/omamobile/fingerprint.conf) counts as the human's go for that phone's first storageproxyd run. Every other fingerprint rule stays: persist and mfg_data are never written, the TDP copy stays read-only, and a phone without the record still needs the human's go. Added: one storage proxy per boot (reboot, never restart), never restore an old TD, and phone-provision's new --fingerprint/--restore-td split. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BeEcdVeSfyLCbijF8XQF1d --- AGENTS.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0ac23021a..7e5c27c06 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,7 +7,7 @@ Omarchy Mobile runs native Omarchy (Arch Linux ARM, Hyprland, Omarchy's packages ## 1. Safety rules (non-negotiable) -- **Ask the human before every reboot, flash, `push`, overlay boot or irreversible write.** That includes RPMB writes, a first `storageproxyd` run, `devinfo` and anything under `/dev/sd*`. The phone is real hardware with calibration data that can't be replaced, and a human has to be ready to recover it. +- **Ask the human before every reboot, flash, `push`, overlay boot or irreversible write.** That includes RPMB writes, a first `storageproxyd` run, `devinfo` and anything under `/dev/sd*`. One recorded exception: on a phone installed with `tools/install-phone`, the owner's install-time acknowledgement (`/etc/omamobile/fingerprint.conf`, `CONSENT=yes`) is the human's go for that phone's first `storageproxyd` run (fingerprint below). The phone is real hardware with calibration data that can't be replaced, and a human has to be ready to recover it. - **The phone is shared with a human. Announce anything that affects the screen or the feel of the phone before you run it**: DPMS, display modes and refresh rate, brightness, `bl_power`, haptics, the torch, the shell restarting, rotation. Otherwise they think the phone is broken, or it buzzes in their hand. - **Only slot B and `userdata` are ours.** Write only `boot_b`, `init_boot_b`, `vendor_boot_b`, `vendor_kernel_boot_b` and `dtbo_b`, and only through `bin/omamobile flash|push` or, on a phone whose `/etc/omamobile/boot-update.conf` says `AUTO_WRITE=yes` (only `tools/install-phone` writes it, for a release install, or a human by hand in an approved runbook), `linux-omamobile`'s pacman hook `omamobile-boot-update` ([RELEASES](docs/RELEASES.md) §5.3, §12 decisions 3 and 10): it writes only `_b` for the descriptor's `BOOT_IMAGES`, each found by GPT name on the main LUN, on `UFS_RW` and left `ro` 0 by the storage guard, read back by sha256, and never reboots. A development phone has no such file, so `push` stays its only writer. Never touch bootloader, radio, `devinfo`, `persist`, `efs*`, `modem*` or `vbmeta`, and never run an unsuffixed `fastboot flash`, with one exception: `userdata`, and only through `tools/install-phone` (serial pinned, codename typed, allowlist, dry run first). Slot A's stock Android is the way back. - **Qualcomm A/B phones (Pixel 4 family) keep the slot flags in GPT attributes,** so slot B can only be marked bootable by writing the partition table. That write is a narrow, named exception, never automatic: by hand, once per install of slot B's boot image, and only for a device whose entry in [CONTRIBUTING](CONTRIBUTING.md) §3.1 names the LUN, the four sectors (LBAs 1, 2, last-1 and last), the attribute bit and the CRCs it rewrites. That device's plan must also record the slot flags before and after, the rollback for a corrupted GPT, and the way back: stock restored on slot A first, or the owner's explicit acceptance of buttons-only recovery. The storage guard can't block this write, so it never runs from a service or at boot. @@ -103,7 +103,7 @@ tools/phone-ssh CMD -> run anything; stream files with ssh 'cat > f' < f | `tools/build-packages`, `tools/build-rootfs` | aarch64 packages (signed, `out/repo`) and the root image, built on the laptop in an Arch Linux ARM container (qemu-user); no phone | | `tools/install-phone` | The installer: fastboot checks, the owner's answers into a local image copy, then only slot B's images and `userdata`. Asks the human to type the codename; `--dry-run` first. Never run it without the human's go | | `tools/nv-backup DIR`, `--check DIR` | The read-only backup of the radio and calibration partitions (the descriptor's `NV_PARTS` and `NV_BACKUP_EXTRA`) over USB SSH, found by `PARTNAME`, refused unless all are read-only and unmounted, each copy verified against a second read on the phone; `--check` is the checksum check of section 1 against such a backup. The output holds the IMEI: never commit or share it | -| `tools/phone-provision` | After a fresh install: Google's files from the user's factory image and the phone's own data from the backup. `--fingerprint` copies Trusty's state but never starts the service | +| `tools/phone-provision` | After a fresh install: Google's files from the user's factory image and the phone's own data from the backup. `--fingerprint` copies only the calibration and `persist:/ss` copies (the runner makes both itself on a new install), `--restore-td` also Trusty's TD and the enrolled fingers, valid only if no storageproxyd ran since the backup; it never starts the service | | `tools/build-packages`, `tools/repo-push` | Maintainer only: the signed `[omamobile]` repository, built on the laptop with no phone (needs `keys/`, never committed); the release key's layout is in [RELEASES](docs/RELEASES.md) §10 (`tools/release-key-init`, run once); `tools/repo-publish` publishes to `pkgs.omamobile.org` (development daily from `origin/main`, stable on the maintainer's go). `tools/repo-build` builds on a connected phone instead: an opt-in shortcut for Mesa, Hyprland and libcamera, never a requirement | | `tools/release-upload [--dry-run] [--full] [--latest] BUNDLE` | Maintainer only: upload a signed bundle and its root image to `pkgs.omamobile.org/releases///` ([RELEASES](docs/RELEASES.md) §6). It checks the signature, the checksums and `manifest.json` first, uploads into a staging directory that is renamed into place, never overwrites a version, and reads every file back over HTTPS. The server side (CORS, MIME types, caching) is `tools/server/releases-nginx.sh`, which the maintainer runs with sudo on the server. Never run either without the human's go | | `tools/release [--dry-run] [--version YYYY.MM.DD] STAGE` | Maintainer only: [RELEASES](docs/RELEASES.md) §11 as stages run in order (`status`, `kernel`, `build`, `images`, `packages`, `rootfs`, `bundle`, `test-install`, `identifiers`, `verify`, `upload`, `promote`, `tag`), each checking what the ones before it recorded in `out/release//state`. It builds the release kernel into its own `$KERNEL_BASE/out-kernel-release` and refuses a directory holding a development build; the steps that push, upload, promote or need the attended install stop and print the command. `scan` and `check-bundle` run the identifier and bundle checks alone. Never run a stage that builds or publishes without the human's go; `--dry-run` first | @@ -156,7 +156,7 @@ Each entry gives the gotcha, then the reason or the fix. Details are in the link - **ACPM reads its channel table from APM SRAM, and some channels are unusable** (a type-2 buffer channel with queues in DRAM): skip them rather than failing the probe. DVFS is channel 0, PMIC 2, thermal 9. Upstream supports polling only. [ACPM-PLAN](device/cheetah/ACPM-PLAN.md) - **The regulator core turns off unused rails that have constraints about 30 s after late init:** load PMIC regulator modules after that, or make sure the rails are claimed. Since #227 the shared kernel builds `sec_acpm` in (the Pixel 9a's USB PHY needs its S2MPG14 rails at boot), so on the 7 Pro the S2MPG13 rails in the DT register before that cleanup and a `blacklist sec_acpm` does nothing; LDO9S-11S are GNSS-only, and LDO15S (`vdd_udfps`, the fingerprint sensor) and LDO12S (`vddio_cam`, camera I/O) are claimed by their drivers when those load, so the cleanup only turns off rails with no consumer yet. The fingerprint and camera starts' `modprobe sec_acpm` is a no-op there too. [GNSS-PLAN](device/cheetah/GNSS-PLAN.md) - **The AoC starts only through Trusty** (`com.android.trusty.gsa.hwmgr.aoc`). The GSA mailbox `START` leaves the A32 held. So Trusty is a dependency of audio and sensors, not just of fingerprint, and it runs at every boot on the integration kernel. -- **Fingerprint: nothing writes `persist` or the RPMB without the human's explicit go.** The first `storageproxyd` run (FINGERPRINT-PLAN F4) is irreversible, and `omamobile-fp.service` ships disabled because its first run writes Trusty's secure storage. [FINGERPRINT-PLAN](device/cheetah/FINGERPRINT-PLAN.md) +- **Fingerprint: nothing writes `persist` or the RPMB without the human's explicit go.** The first `storageproxyd` run is irreversible (an RPMB write, the same kind as an Android factory reset). Since 2026-11-02 the owner's recorded install-time acknowledgement counts as that go on their phone: `tools/install-phone`'s warning names the write, typing the codename acknowledges it, and firstboot records it in `/etc/omamobile/fingerprint.conf` and enables `omamobile-fp` (the package still ships it disabled). The runner (`omamobile-fp-chroot`, omamobile-fingerprint 0.1.14) refuses the first storage start without that record, makes the read-only copies of `mfg_data` and `persist:/ss` itself, and refuses storageproxyd without the TDP copy or when the copy or `persist:/ss/0` no longer matches its recorded hash. Every other rule stands: `persist` and `mfg_data` are never written, the TDP copy stays read-only, nothing touches the Titan M2, and on a phone without the record (set up by hand, or an agent's runbook) ask first. **One storage proxy per boot:** never stop and start `omamobile-fp` (or any storageproxyd) in the same boot; Trusty keeps its storage state until a reboot, and a restart between TD's clear and its first commit crashed Trusty's storage app (F19). Reboot instead; the runner refuses a second start. Never restore an old TD. [FINGERPRINT-PLAN](device/cheetah/FINGERPRINT-PLAN.md) F19 - **Set the Bluetooth address only after powering the controller on:** set on a never-powered controller, the kernel withdrew the index for good. - **spi-s3c64xx with automatic chip select dropped bits between transfers before linux-omarchy-mobile#150 (merged 2026-10-31):** its FIFO flush cleared the packet count before turning the channels off, so the controller clocked a few bits with the slave still selected. A slave that restarts per chip-select cycle (touch) doesn't notice; one that streams across cycles (the 9a's GNSS core, CHPP) loses 2-6 bits per transfer, and every read lands at a different bit offset. [tegu MODEM-PLAN](device/tegu/MODEM-PLAN.md) "G3, GNSS gets a fix" - **A node without pinctrl runs on the bootloader's pins, and a pin change tested next to another fix proves nothing on its own.** The 9a's GNSS SPI has no pin group and runs at the bootloader's drive 0; raising the drive looked like it cleaned the data, but it was tested together with the SPI flush fix, and with the flush fix alone at drive 0 the data was just as clean (linux-omarchy-mobile#151 closed). Read the bank's CON/PUD/DRV in `/sys/kernel/debug/pinctrl//pins` (one controller at a time, as the gs101 note above says) before changing anything, then change one thing per boot, and check whose pins they are in the vendor tree before claiming them (gpp22 is the eSE's). [tegu MODEM-PLAN](device/tegu/MODEM-PLAN.md) "G3, GNSS gets a fix" From 74cb007eceafdf148bc3b0a83cdbeac690b05450 Mon Sep 17 00:00:00 2001 From: Derek Ross Date: Mon, 2 Nov 2026 18:01:37 -0500 Subject: [PATCH 08/15] INSTALL, DEVICES, release notes: fingerprint works out of the box after provisioning INSTALL.md replaces "not available on a new install yet" (#354) with what happens now: after the provisioning restart the phone offers "Add a fingerprint", with the install warning's risk text (the secure-storage write, the same kind as a factory reset, nothing to persist, mfg_data, the Titan M2 or slot A; fingerprint stays off if the read-only copies can't be made or stop matching; restart the phone rather than the service). Going back to Android says fingers are enrolled again on each side. DEVICES.md and the release-notes draft follow. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BeEcdVeSfyLCbijF8XQF1d --- docs/DEVICES.md | 2 +- docs/INSTALL.md | 4 ++-- docs/release-notes/2026-11-DRAFT.md | 5 +++-- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/DEVICES.md b/docs/DEVICES.md index 4f4adbbd4..1f9504aee 100644 --- a/docs/DEVICES.md +++ b/docs/DEVICES.md @@ -56,7 +56,7 @@ The status of each device, as verified on real hardware. Rows in the matrix have | NFC | works | ST54J over I2C through st-nci with our plain-NCI link, loaded at boot; neard (patched for empty Type 4 tags) reads and writes tags, and tapping a tag with a web link opens it (`omamobile-nfc-open`): writing a tag and opening its link tested on the phone (N3). Card emulation and the secure element are not used | [RADIOS-CAMERA-PLAN](../device/cheetah/RADIOS-CAMERA-PLAN.md) §3 | | Cameras | works (telephoto fixed-focus) | Ultrawide (Sony IMX386, D-PHY link 2): works end to end through our CSIS/WDMA driver and libcamera's software ISP (CAM5), basic quality (no Google ISP or tuning); a libcamera build with autofocus and low-light patches is installed, not yet evaluated (CAM5.3). Front (Samsung S5K3J1, D-PHY link 0): real images, raw and through libcamera (`cam -c1`, 30 fps, no WDMA errors; F.5-F.7, 2026-10-13). Main (Samsung S5KGN1, C-PHY link 1): 2016x1136 at 30 fps through libcamera with no WDMA errors. Telephoto (S5KGM5, C-PHY): 26 fps through libcamera, colour bars correct; its lens (SEM1215) isn't driven yet, so it stays at its resting focus: distant subjects are sharp (outdoors, 2026-10-26), close ones soft, and tap to focus does nothing. The CSIS write DMA (not the link) loses lines that arrive faster than about 400 MB/s within a line, so the sensors lengthen their lines to stay under `samsung,max-line-throughput` (360 in cheetah's DT for the main, telephoto and front cameras; the front's full 3840x2736 mode runs at 26 fps). The ultrawide (imx386) follows the same rule, so its full 4032x3016 mode streams (23 fps; one run in several still showed WDMA errors), and with 384 MiB of CMA `cam` without options runs every camera at full size (main 12 MP at 9.4 fps). The telephoto's lens (SEM1215) answers on a 950 kHz bus but holds the bus when driven longer, so the telephoto runs at fixed focus. Sensor and DC-PHY settings come from the user's own camera software (`tools/extract-camera-data`), never shipped. Since omamobile-device-cheetah 0.1.30 the camera modules load after boot (`omamobile-camera.timer`), the DMA-BUF heaps are open to the session (libcamera's software ISP), WirePlumber names them Main, Ultrawide, Telephoto and Front camera (0.1.31). The default camera app is omacam ("Camera", omamobile-apps 0.2.0; [CAMERA-APP-PLAN](CAMERA-APP-PLAN.md)): libcamera directly, zoom across the three back lenses, full-resolution photos. GNOME Snapshot is optional, named "Snapshot", for video until omacam records it; browsers and video calls use the cameras through PipeWire (`pipewire-libcamera`). Picture quality: libcamera 0.7.2-4.21 adds chroma noise reduction and defective pixel correction, and omacam 0.3.3 has Night mode and an HDR chip, bursts of raw frames aligned, merged and finished on the phone (Night: 12 frames in about 4.6 s, Q5.3 on 2026-10-21); single shots are still well below stock's | [CAMERA-PLAN](../device/cheetah/CAMERA-PLAN.md), [CAMERA-QUALITY-PLAN](CAMERA-QUALITY-PLAN.md) | | Suspend | WIP | s2idle works when asked for (`systemctl suspend`, `rtcwake`): `pm_test` dry runs, wakes on a volume key and on the RTC alarm, 20 of 20 unattended cycles (S3b, S4); UFS powers down in suspend by default (`spm_lvl` 5). Wi-Fi stays connected across sleep: 31 of 31 freezes with the D3 handshake (S5b-3, S5c, 2026-10-19), and the sleep hook keeps it loaded. The AoC and sensors work across sleep, and a running sensor stream doesn't wake the phone (S6, 2026-10-19). Screen off, with Wi-Fi up, it draws 434 mA awake and 312 mA in s2idle: about 16 h of standby on the 4986 mAh battery (S7, 2026-10-19), against 32-50 mA in stock's deep sleep. Auto-sleep is in the packages and off by default ([#64](https://github.com/derekross/omarchy-mobile/pull/64), omamobile-shell 0.2.29): with the `omamobile-sleep` toggle on, the phone sleeps 30 s after the screen goes off behind a secure lock and at once on Power, and Power wakes it to the PIN pad; 13 cycles in one boot with 0 failures (P0-P5, 2026-10-26). P5 stopped that day on a speaker trip that turned out not to come from sleep ([NOTES](../device/cheetah/NOTES.md#2026-10-27-the-muted-speakers-were-the-open-loop-coil-estimate-not-sleep-the-static-was-the-boost-converter-the-earpiece-is-the-top-speaker)); resumed on 2026-11-01, it passed with 11 suspends and 0 failures, the speakers fine across each sleep. After its power-key test Hyprland ran neither power-key bind until `hyprctl reload`; the on-screen keyboard's virtual keyboard was reaching the hardware-key binds, which now ignore it ([#312](https://github.com/derekross/omarchy-mobile/pull/312), omamobile-shell 0.2.75; re-tested on the phone 2026-11-01, [SUSPEND-PLAN](../device/cheetah/SUSPEND-PLAN.md) P5 test h). Still open: NetworkManager drops Wi-Fi for each sleep and reconnects about 5 s after the wake. The toggle stays off by default until a day of use (P6) and a power-off from Linux (P7) have run. Wi-Fi traffic and a USB plug can't wake it, a few RTC cycles wake early on a PMIC interrupt not yet identified, and the modem has never run across a suspend. Deep sleep (SYS_SLEEP), which stock's standby numbers need, is research and not started | [SUSPEND-PLAN](../device/cheetah/SUSPEND-PLAN.md) | -| Fingerprint | works (opt-in) | Google's HAL in a chroot behind a bridge and Trusty's fingerprint TA on our kernel (F3-F9), fprintd with our libfprint driver: enrollment from the shell, and the lock screen unlocks with a finger alongside the PIN pad or password, with the keyboard usable over the lock (F16b). A verify stays open across system sleep, and an enrollment interrupted by sleep fails cleanly (libfprint 1.6, 2026-10-19). Opt-in: `omamobile-fp.service` ships disabled, because its first run writes Trusty's secure storage | [FINGERPRINT-PLAN](../device/cheetah/FINGERPRINT-PLAN.md), [FINGERPRINT-RESEARCH](../device/cheetah/FINGERPRINT-RESEARCH.md) | +| Fingerprint | works (on by default for new installs) | Google's HAL in a chroot behind a bridge and Trusty's fingerprint TA on our kernel (F3-F9), fprintd with our libfprint driver: enrollment from the shell, and the lock screen unlocks with a finger alongside the PIN pad or password, with the keyboard usable over the lock (F16b). A verify stays open across system sleep, and an enrollment interrupted by sleep fails cleanly (libfprint 1.6, 2026-10-19). From omamobile-fingerprint 0.1.14 and omamobile-firstboot 0.1.4 it is on for new installs: the installer's warning names the secure-storage write and the typed codename is the consent, the runner makes its read-only copies itself and runs one storage proxy per boot (F19, 2026-11-02; the fresh-install checks T1-T3 are pending) | [FINGERPRINT-PLAN](../device/cheetah/FINGERPRINT-PLAN.md), [FINGERPRINT-RESEARCH](../device/cheetah/FINGERPRINT-RESEARCH.md) | ## Wanted diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 03d8a7137..5c66b9477 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -197,7 +197,7 @@ tools/phone-ssh '(sleep 1; reboot-to omamobile) >/dev/null 2>&1 &' After the restart, Wi-Fi, Bluetooth, sound, haptics, the sensors and the cameras work. -**Fingerprint unlock isn't available on a new install yet.** Its service writes the phone's secure storage, and before its first start it needs read-only copies of data that stock Android keeps in the phone's `persist` partition. Nothing on a new install makes those copies yet, and starting the service without them could damage that stock storage for good. **Don't start `omamobile-fp` by hand.** A coming release turns fingerprint on safely as part of the install. +**Fingerprint unlock works out of the box.** After this restart the phone offers "Add a fingerprint" (or find it later in Setup > Security > Fingerprint): touch the sensor under the bright circle until it's done, and the finger unlocks the phone alongside your PIN or password. As the installer's warning said, fingerprint's first start writes the phone's secure storage (Trusty's area in the UFS RPMB). That can't be undone, but it is the same kind of write Android makes at every factory reset. Before that first start the phone makes read-only copies of the data it needs from `persist` and the factory calibration (`mfg_data`); nothing is written to `persist`, `mfg_data`, the Titan M2 security chip or Android's slot A, and if those copies can't be made or later don't match, fingerprint stays off and the PIN unlocks. If fingerprint ever stops (after a crash, for example), restart the phone rather than restarting the service. ## Getting updates @@ -224,7 +224,7 @@ Stock Android is still on slot A. fastboot reboot ``` -3. Android starts into its recovery screen, because its data was erased. Choose "Factory data reset", and Android starts as a new phone. +3. Android starts into its recovery screen, because its data was erased. Choose "Factory data reset", and Android starts as a new phone. Fingerprints you enrolled on Omarchy Mobile stay behind: enroll your fingers again on Android (and again after you come back, since reinstalling erases them; never restore an old fingerprint backup). To remove Omarchy Mobile completely, flash Google's factory image for your phone with Google's own tools (the [Android Flash Tool](https://flash.android.com) or the `flash-all.sh` script in the factory image). Don't lock the bootloader afterwards unless you're sure both slots hold Google's images; if in doubt, ask in an issue first. diff --git a/docs/release-notes/2026-11-DRAFT.md b/docs/release-notes/2026-11-DRAFT.md index afc02579a..b736c10a8 100644 --- a/docs/release-notes/2026-11-DRAFT.md +++ b/docs/release-notes/2026-11-DRAFT.md @@ -37,7 +37,7 @@ From [docs/DEVICES.md](../DEVICES.md) on the release day: | GNSS | Location through GeoClue, with a quick-settings tile | | NFC | Reads and writes tags; a tag with a link opens it | | Cameras | Main, ultrawide and front through libcamera; the telephoto at fixed focus | -| Fingerprint | Opt-in: enrollment and unlock on the lock screen | +| Fingerprint | On out of the box after provisioning: enrollment offered at setup, unlock on the lock screen | | CPU | Frequency scaling and thermal zones | ### New in the last weeks @@ -50,6 +50,7 @@ From [docs/DEVICES.md](../DEVICES.md) on the release day: - **Updates** entry in the app drawer, with an update sheet that shows what's new and the phone's patches. - **Louder speakers** under the protection firmware, and an earpiece mode for calls. - **Files** opens folders with a single tap; the file chooser no longer stalls at login. +- **Fingerprint out of the box:** the installer's warning covers its secure-storage write, the phone makes its read-only copies of the calibration and `persist:/ss` itself, and setup offers "Add a fingerprint" after the PIN. ## Known issues @@ -58,7 +59,7 @@ From [docs/DEVICES.md](../DEVICES.md) on the release day: - **Cameras:** basic image quality (no Google ISP or tuning); the telephoto doesn't focus. - **Bluetooth:** headset calls (HFP) don't work yet. - **USB-C:** the phone is a USB device only (no host mode or role switch yet); after a replug, `omamobile-usb-rescue` reconnects it. -- **Fingerprint** is opt-in because its first run writes Trusty's secure storage on the phone. +- **Fingerprint's first start writes the phone's secure storage** (Trusty's area in the RPMB, the same kind of write as an Android factory reset; nothing goes to `persist`, `mfg_data`, the Titan M2 or slot A). The installer's warning says so, and typing the codename acknowledges it. Going back to Android works as usual, with fingers enrolled again there. If fingerprint stops, restart the phone: it starts once per boot by design. - **Google's firmware is not included** and never will be: after installing, the bundle's `tools/phone-provision` extracts it from your own factory image for your phone (Wi-Fi, Bluetooth, haptics, speakers, cameras). ## Phones already running a development build From dfbebe73b1d0f3703163ac433918a9c9fa07af15 Mon Sep 17 00:00:00 2001 From: Derek Ross Date: Mon, 2 Nov 2026 18:34:27 -0500 Subject: [PATCH 09/15] omamobile-fingerprint 0.1.14: on by default, no consent step; the data guards kept and hardened The maintainer decided (2026-11-02) that fingerprint simply works out of the box: no consent record. The runner's consent check (and its "TD already exists" exception) goes, and the package enables omamobile-fp itself with a vendor wants link, so only a runner with the guards is ever enabled by default. The unit stays inert until tools/phone-provision has pushed Google's files. Kept: the read-only copies of mfg_data and persist:/ss/{0,nsp} (debugfs, no mount, ro=1 checks), the recorded hashes, the refusal when the TDP copy is missing or differs or persist:/ss/0 changed, one storage proxy per boot, no Restart=, the stop order. Fixed and hardened, from the round-1 review of #358: - alive() read the host's /proc for namespace PIDs, so the ordered stop waited on unrelated host processes (or not at all). It now reads the namespace's procfs at $ROOT/proc; test/all checks it in a real PID namespace (and fails on the old code). - The inner start refuses without the token this boot's preflight wrote into the /run marker, so OMAMOBILE_FP_IN_NS=1 can't skip the checks; the path overrides of the guard's inputs need OMAMOBILE_FP_TEST=1. - An EXIT trap in the namespace keeps the stop order on a die. - An existing mfg_data.img is adopted only if it matches the partition; otherwise it is moved aside and copied again. - A start that never reached "running" (Trusty halted, which also takes the AoC's sound and sensors) leaves a marker in $STATE: the next boot skips fingerprint once, the one after tries again. - post_upgrade sets the per-boot marker when an older runner's storage proxy is still running, so the upgrade boot can't start a second one. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BeEcdVeSfyLCbijF8XQF1d --- packages/omamobile-fingerprint/install | 7 +- .../lib/omamobile-fp-chroot | 119 +++++++++++------- .../omamobile-fingerprint.install | 16 ++- packages/omamobile-fingerprint/test/all | 46 +++++++ packages/omamobile-fingerprint/test/preflight | 107 ++++++++++------ .../systemd/system/omamobile-fp.service | 9 +- 6 files changed, 207 insertions(+), 97 deletions(-) diff --git a/packages/omamobile-fingerprint/install b/packages/omamobile-fingerprint/install index ec6921398..cbe06a891 100755 --- a/packages/omamobile-fingerprint/install +++ b/packages/omamobile-fingerprint/install @@ -1,6 +1,6 @@ #!/bin/bash # SPDX-License-Identifier: MIT -# Stage omamobile-fingerprint into DESTDIR. Enables nothing. Google's Android +# Stage omamobile-fingerprint into DESTDIR. Google's Android # files are not part of the package: tools/extract-fingerprint-vendor makes # them from the user's own factory image (/usr/lib/omamobile-fp/root, # MANIFEST, SOURCE). The bionic programs are built on the computer first: @@ -21,6 +21,11 @@ install -Dm644 lib/props-tegu.conf "$l/props-tegu.conf" install -Dm644 prebuilt/omamobile-fp-shim.so "$l/omamobile-fp-shim.so" install -Dm755 prebuilt/omamobile-fp-bridge "$l/omamobile-fp-bridge" install -Dm644 vendor/systemd/system/omamobile-fp.service "$d/usr/lib/systemd/system/omamobile-fp.service" +# Enabled by a vendor wants link: fingerprint starts by default, and only +# with this runner (its copies, TDP guard and one proxy per boot). The unit is +# inert until tools/phone-provision has pushed Google's files. +install -d "$d/usr/lib/systemd/system/multi-user.target.wants" +ln -sfn ../omamobile-fp.service "$d/usr/lib/systemd/system/multi-user.target.wants/omamobile-fp.service" install -Dm644 vendor/pam.d/omarchy-lock-fingerprint "$d/etc/pam.d/omarchy-lock-fingerprint" install -Dm644 vendor/systemd/system/fprintd.service.d/omamobile-udfps.conf \ "$d/usr/lib/systemd/system/fprintd.service.d/omamobile-udfps.conf" diff --git a/packages/omamobile-fingerprint/lib/omamobile-fp-chroot b/packages/omamobile-fingerprint/lib/omamobile-fp-chroot index ce7e7f9e1..b798ffb29 100755 --- a/packages/omamobile-fingerprint/lib/omamobile-fp-chroot +++ b/packages/omamobile-fingerprint/lib/omamobile-fp-chroot @@ -6,10 +6,12 @@ # # omamobile-fp-chroot check preconditions only; changes nothing # omamobile-fp-chroot preflight the safety checks a start runs before -# storageproxyd (consent, the read-only -# copies, the TDP guard, once per boot); -# on success it counts as this boot's -# start (start runs it itself) +# storageproxyd (the read-only copies, +# the TDP guard, once per boot). Not a +# dry check: it makes the copies, and on +# success it counts as this boot's start, +# so the service then refuses until a +# reboot (start runs it itself) # omamobile-fp-chroot start [STAGE] start the stack up to STAGE, in the # foreground (systemd runs it), and # supervise it until stopped @@ -34,11 +36,6 @@ # Safety before storageproxyd (preflight; FINGERPRINT-PLAN F19 and # section 4). Every start runs storageproxyd, and Trusty's storage writes # the RPMB, so: -# - consent: the storage stage runs only when /etc/omamobile/fingerprint.conf -# says CONSENT=yes (omamobile-firstboot writes it from the installer's -# acknowledgement; a missing file or key is no), or when this install's -# secure storage already exists (a phone whose first run had the human's -# go during bring-up); # - the read-only copies (the 7 Pro): at the first start it copies # mfg_data (dd) and persist:/ss/0 and /ss/nsp (debugfs, which reads the # partition without mounting it) into $STATE and records their sha256 in @@ -52,7 +49,17 @@ # - once per boot: Trusty keeps each store's state for the whole boot, and # a storage proxy stopped and started again in the same boot crashed # Trusty's storage app on 2026-11-02 (FINGERPRINT-PLAN F19). A marker in -# /run refuses a second start until a reboot. +# /run refuses a second start until a reboot, and the inner start +# (in the namespace) runs only with the token preflight wrote there; +# - a start that never got running: a marker in $STATE is set before +# storageproxyd and cleared once the stack runs. Found at the next boot, +# it means that start died on the way (Trusty halted, which also takes +# the AoC's sound and sensors with it), so that boot skips fingerprint +# once and the one after tries again. +# +# The overrides of the partitions' and markers' paths (OMAMOBILE_FP_RUN, +# _SYSBLOCK, _DEVDIR, _MOUNTS, _BOOT_ID) are honoured only with +# OMAMOBILE_FP_TEST=1, which the unit never sets (test/preflight). set -euo pipefail IMAGE=${OMAMOBILE_FP_IMAGE:-/usr/lib/omamobile-fp/root} @@ -96,14 +103,23 @@ esac PANEL_NAME=${OMAMOBILE_FP_PANEL_NAME:-$PANEL_NAME} PROPS_DEVICE=${OMAMOBILE_FP_PROPS_DEVICE:-/usr/lib/omamobile-fp/props-$DEVICE.conf} STATE=${OMAMOBILE_FP_STATE:-/var/lib/omamobile-fp} -RUN=${OMAMOBILE_FP_RUN:-/run/omamobile-fp} -# The owner's install-time acknowledgement (omamobile-firstboot writes it). -CONSENT=${OMAMOBILE_FP_CONSENT:-/etc/omamobile/fingerprint.conf} -# Where the partitions are found (tests point these at a fake tree). -SYSBLOCK=${OMAMOBILE_FP_SYSBLOCK:-/sys/class/block} -DEVDIR=${OMAMOBILE_FP_DEVDIR:-/dev} -MOUNTS=${OMAMOBILE_FP_MOUNTS:-/proc/mounts} +RUN=/run/omamobile-fp +# Where the partitions are found +SYSBLOCK=/sys/class/block +DEVDIR=/dev +MOUNTS=/proc/mounts +BOOT_ID_FILE=/proc/sys/kernel/random/boot_id +# test/preflight points these at a fake tree; nothing else may +if [[ ${OMAMOBILE_FP_TEST:-} == 1 ]]; then + RUN=${OMAMOBILE_FP_RUN:-$RUN} + SYSBLOCK=${OMAMOBILE_FP_SYSBLOCK:-$SYSBLOCK} + DEVDIR=${OMAMOBILE_FP_DEVDIR:-$DEVDIR} + MOUNTS=${OMAMOBILE_FP_MOUNTS:-$MOUNTS} + BOOT_ID_FILE=${OMAMOBILE_FP_BOOT_ID:-$BOOT_ID_FILE} +fi PROVENANCE=$STATE/provenance +# Set before storageproxyd, cleared once the stack runs (see the header). +PENDING=$STATE/start-pending # Set once storageproxyd may have started this boot; /run goes with the # reboot, which is exactly when Trusty's state does. MARKER=$RUN/storageproxyd-started @@ -134,10 +150,12 @@ die() { say "error: $*"; exit 1; } # env(1) would look chroot up in that. CHROOT_BIN=$(PATH=/usr/bin:/bin:/usr/sbin:/sbin command -v chroot || true) -# A supervised child still running (not gone, not a zombie)? +# A supervised child still running (not gone, not a zombie)? PIDS[] holds +# the namespace's PIDs, so this reads the namespace's procfs, which setup() +# mounts at $ROOT/proc; the host's /proc would answer for another process. alive() { local st - st=$(sed 's/^.*) //' "/proc/$1/stat" 2>/dev/null) || return 1 + st=$(sed 's/^.*) //' "$ROOT/proc/$1/stat" 2>/dev/null) || return 1 [[ -n $st && ${st%% *} != Z ]] } @@ -222,28 +240,13 @@ check() { [[ -f $STATE/mfg_data.img ]] || say "no $STATE/mfg_data.img yet: the first start copies it from mfg_data" fi - if consent_given; then say "consent: yes ($CONSENT)" - elif storage_exists; then say "consent: no record, but this install's secure storage already exists" - else say "consent: no (no CONSENT=yes in $CONSENT): the storage stage will refuse"; fi - [[ ! -e $MARKER ]] || say "storageproxyd already started this boot: a new start needs a reboot" + [[ -n ${OMAMOBILE_FP_IN_NS:-} || ! -e $MARKER ]] || say "storageproxyd already started this boot: a new start needs a reboot" ((ok)) || exit 1 say "preconditions met" } # --- Safety before storageproxyd (see the header) --------------------------- -# CONSENT=yes in the consent file. Data, never sourced; anything else is no. -consent_given() { - [[ -f $CONSENT ]] && grep -qx 'CONSENT=yes' "$CONSENT" -} - -# This install's TD already exists: storageproxyd ran here before (on the -# bring-up phones, with the human's go), so the irreversible first run is -# behind it. -storage_exists() { - [[ -s $STATE/data/vendor/ss/0 || -L $STATE/data/vendor/ss/0 || -f $STATE/td.img ]] -} - # The block device name of a partition, by PARTNAME (the Arch root has no # /dev/disk/by-partlabel). part_dev() { @@ -306,10 +309,16 @@ provision() { [[ ! -f $tmp/nsp ]] || mv "$tmp/nsp" "$STATE/persist-ss/nsp" say "copied persist:/ss read-only (debugfs; persist is never mounted)" fi - if [[ ! -s $STATE/mfg_data.img ]]; then - dd if="$DEVDIR/$m" of="$tmp/mfg_data.img" bs=1M status=none || die "can't read mfg_data" - [[ -s $tmp/mfg_data.img ]] || die "mfg_data read empty" - chmod 0600 "$tmp/mfg_data.img" + dd if="$DEVDIR/$m" of="$tmp/mfg_data.img" bs=1M status=none || die "can't read mfg_data" + [[ -s $tmp/mfg_data.img ]] || die "mfg_data read empty" + chmod 0600 "$tmp/mfg_data.img" + if [[ -s $STATE/mfg_data.img ]] && cmp -s "$tmp/mfg_data.img" "$STATE/mfg_data.img"; then + say "the existing mfg_data.img matches the partition: recording it" + else + if [[ -e $STATE/mfg_data.img ]]; then + mv -- "$STATE/mfg_data.img" "$STATE/mfg_data.img.before-provision.$(date +%Y%m%d%H%M%S)" + say "the existing mfg_data.img differs from the partition: moved aside, copied again" + fi mv "$tmp/mfg_data.img" "$STATE/mfg_data.img" say "copied mfg_data read-only (the factory calibration; the partition is never written)" fi @@ -365,19 +374,24 @@ tdp_guard() { # on this boot's storage proxy counts as started, even if a later step fails. preflight() { if [[ -e $MARKER ]]; then - die "secure storage already ran this boot ($(cat "$MARKER" 2>/dev/null || true)): Trusty keeps its storage state until a reboot, and a second storage proxy in the same boot can crash it. Reboot to start fingerprint again" + die "secure storage already ran this boot ($(sed "s/ token .*//" "$MARKER" 2>/dev/null || true)): Trusty keeps its storage state until a reboot, and a second storage proxy in the same boot can crash it. Reboot to start fingerprint again" fi - if consent_given; then - say "consent: the owner's install-time acknowledgement ($CONSENT)" - elif storage_exists; then - say "no consent record in $CONSENT, but this install's secure storage already exists (its first run had the human's go)" - else - die "no consent for the first secure-storage write: $CONSENT has no CONSENT=yes (the installer's acknowledgement writes it). Nothing started" + local boot pending + boot=$(cat "$BOOT_ID_FILE" 2>/dev/null || echo unknown) + if [[ -f $PENDING ]]; then + pending=$(cat "$PENDING" 2>/dev/null || true) + if [[ ${pending%% *} != "$boot" ]]; then + rm -f "$PENDING" + die "the last start (${pending#* }) never got running: it may have halted Trusty, which also stops the AoC's sound and sensors. Skipping fingerprint this boot; the next boot tries again (journalctl -b -1 -u omamobile-fp)" + fi fi ((MAP_STORES)) || provision tdp_guard install -d -m 0755 "$RUN" - echo "$(date -Is 2>/dev/null || date) pid $$" > "$MARKER" + TOKEN=$(head -c 16 /dev/urandom | od -An -tx1 | tr -d ' \n') + (umask 077; echo "$(date -Is 2>/dev/null || date) pid $$ token $TOKEN" > "$MARKER") + install -d -m 0700 "$STATE" + echo "$boot $(date -Is 2>/dev/null || date)" > "$PENDING" } # Bind $1 onto $2 (created as a file or directory to match), optionally ro. @@ -579,6 +593,12 @@ declare -A PIDS=() start() { local stage=${1:-bridge} sg case $stage in storage|apploader|keys|hal|bridge) ;; *) die "unknown stage $stage" ;; esac + if [[ -n ${OMAMOBILE_FP_IN_NS:-} ]]; then + # Only after this boot's preflight: its marker carries the token it + # handed down, so OMAMOBILE_FP_IN_NS=1 alone can't skip the checks. + [[ -n ${OMAMOBILE_FP_TOKEN:-} && -f $MARKER && $(sed -n 's/.* token //p' "$MARKER") == "$OMAMOBILE_FP_TOKEN" ]] || + die "the inner start runs only after this boot's preflight (omamobile-fp-chroot start)" + fi # Modules the stack needs, blacklisted from autoload (omamobile-device- # cheetah: omamobile-fingerprint.conf): load them by name, as needed. if [[ -z ${OMAMOBILE_FP_IN_NS:-} ]]; then @@ -599,6 +619,7 @@ start() { # Consent, the read-only copies, the TDP guard, once per boot: every # stage starts storageproxyd. preflight + export OMAMOBILE_FP_TOKEN=$TOKEN # Re-exec in a private mount namespace (and PID namespace, so the # Android processes die with us). Not a network namespace: see above. # systemd signals only this process (KillMode=mixed); unshare hands @@ -613,6 +634,9 @@ start() { # shared with the host until our mounts, so record the host PID for ns/run. awk '/^NSpid:/ {print $2}' /proc/self/status > "$NSPID" trap 'stop 0' TERM INT + # a die from here on (after the proxy may have started) still stops the + # stack in order + trap 'stop $?' EXIT setup "$sg" spawn servicemanager system /system/bin/servicemanager @@ -671,6 +695,7 @@ start() { fi say "stage $stage running" + rm -f "$PENDING" # Supervise: any child exiting stops the whole stack, and it stays stopped # until a reboot (one storage proxy per boot; the unit has no Restart=). wait -n || true diff --git a/packages/omamobile-fingerprint/omamobile-fingerprint.install b/packages/omamobile-fingerprint/omamobile-fingerprint.install index 14e63df63..51a0f9f35 100644 --- a/packages/omamobile-fingerprint/omamobile-fingerprint.install +++ b/packages/omamobile-fingerprint/omamobile-fingerprint.install @@ -1,14 +1,18 @@ # SPDX-License-Identifier: MIT post_install() { - echo "omamobile-fingerprint: nothing enabled by the package. On a release install," - echo " omamobile-firstboot enables omamobile-fp from the owner's install-time" - echo " acknowledgement (/etc/omamobile/fingerprint.conf); it starts once Google's" - echo " files are in /usr/lib/omamobile-fp/root (tools/phone-provision). Its first" - echo " start copies persist:/ss and mfg_data read-only and writes Trusty's secure" - echo " storage; without the acknowledgement it refuses (FINGERPRINT-PLAN F19)." + echo "omamobile-fingerprint: omamobile-fp starts at boot once Google's files are in" + echo " /usr/lib/omamobile-fp/root (tools/phone-provision). Its first start copies" + echo " mfg_data and persist:/ss read-only and writes Trusty's secure storage." } post_upgrade() { systemctl daemon-reload 2>/dev/null || true + # A storage proxy an older runner started this boot left no marker: set it, + # so the new runner refuses a second proxy until the reboot. + if pgrep -x storageproxyd >/dev/null 2>&1 && [[ ! -e /run/omamobile-fp/storageproxyd-started ]]; then + mkdir -p /run/omamobile-fp + (umask 077; echo "$(date -Is) started before the upgrade token none" > /run/omamobile-fp/storageproxyd-started) + fi + echo "omamobile-fingerprint: fingerprint starts again at the next boot (one storage proxy per boot)" } pre_remove() { systemctl disable --now omamobile-fp.service 2>/dev/null || true diff --git a/packages/omamobile-fingerprint/test/all b/packages/omamobile-fingerprint/test/all index 383f7dc84..0b620cc73 100755 --- a/packages/omamobile-fingerprint/test/all +++ b/packages/omamobile-fingerprint/test/all @@ -76,8 +76,51 @@ grep -c '^KillMode=mixed$' "$u" >/dev/null || fail "systemd signals only the run # Stop order: the bridge and the HAL, then KeyMint and Gatekeeper, the proxy last order=$(sed -n '/^stop() {/,/^}/p' lib/omamobile-fp-chroot | sed -n 's/^ *stop_children [0-9]* //p' | tr '\n' '|') [[ $order == "bridge fingerprint|gatekeeper keymint|storageproxyd|" ]] || fail "stop order: $order" +grep -c 'ln -sfn ../omamobile-fp.service "$d/usr/lib/systemd/system/multi-user.target.wants/omamobile-fp.service"' install >/dev/null || + fail "the package enables omamobile-fp itself (so only this runner is ever enabled by default)" echo "ok - one start per boot, no restart loop, the storage proxy stopped last" +# alive() and stop_children() in a real PID namespace (the runner's PIDS[] +# are the namespace's PIDs): a child that exits on TERM is seen gone at once, +# one that ignores TERM is waited for, and an exited child never reads as +# running because the host has a process with that number. +fns=$(sed -n '/^alive() {/,/^}/p; /^stop_children() {/,/^}/p' lib/omamobile-fp-chroot) +[[ -n $fns ]] || fail "alive and stop_children not found" +nsroot=$(mktemp -d) +if unshare --user --map-root-user --mount --propagation private --pid --fork \ + bash -c 'mkdir -p "$1/proc" && mount -t proc proc "$1/proc"' _ "$nsroot" 2>/dev/null; then + # As in the runner: /proc stays the host's, the namespace's procfs is + # mounted at $ROOT/proc + out=$(unshare --user --map-root-user --mount --propagation private --pid --fork bash -c ' + set -euo pipefail + ROOT=$1 + mount -t proc proc "$ROOT/proc" + say() { echo "say: $*"; } + '"$fns"' + declare -A PIDS=() + sleep 30 & PIDS[quick]=$! + bash -c "trap \"\" TERM; sleep 3" & PIDS[stubborn]=$! + sleep 0.2 + s=$(date +%s%N); stop_children 50 quick; e=$(date +%s%N) + echo "quick_ms=$(( (e - s) / 1000000 ))" + alive "${PIDS[quick]}" && echo "quick=alive" || echo "quick=gone" + alive 2 && echo "pid2=alive" || echo "pid2=gone" + stop_children 10 stubborn + alive "${PIDS[stubborn]}" && echo "stubborn=alive" || echo "stubborn=gone" + kill -KILL "${PIDS[stubborn]}" 2>/dev/null || true + ' _ "$nsroot" 2>&1) + ms=$(sed -n 's/^quick_ms=//p' <<<"$out") + [[ -n $ms ]] && ((ms < 2000)) || fail "a child that exits on TERM is seen gone at once ($out)" + grep -qx 'quick=gone' <<<"$out" || fail "an exited child reads as gone ($out)" + grep -qx 'pid2=gone' <<<"$out" || fail "alive() reads the namespace's processes, not the host's ($out)" + grep -q 'say: still running after 1 s: stubborn' <<<"$out" && grep -qx 'stubborn=alive' <<<"$out" || + fail "a child that ignores TERM is waited for and reported ($out)" + echo "ok - alive() and the ordered stop see the namespace's processes (stops take as long as the children)" +else + echo "ok - alive() in a PID namespace # SKIP no unprivileged user namespaces here" +fi +rmdir "$nsroot/proc" 2>/dev/null; rmdir "$nsroot" 2>/dev/null || true + if [[ ! -f prebuilt/omamobile-fp-shim.so ]]; then echo "ok - the rest # SKIP no bionic prebuilts in this checkout (built on the computer)" exit 0 @@ -112,6 +155,9 @@ done [[ -z $(find "$stage" -path '*/root/*' -print -quit) ]] || fail "vendor files staged" # the modprobe file reached the stage [[ -f $stage/usr/lib/modprobe.d/omamobile-fingerprint-lhbm.conf ]] || fail "not staged: modprobe.d/omamobile-fingerprint-lhbm.conf" +# on by default, with this runner: the package itself enables the unit +[[ $(readlink "$stage/usr/lib/systemd/system/multi-user.target.wants/omamobile-fp.service") == ../omamobile-fp.service ]] || + fail "the package enables omamobile-fp (vendor wants link)" if command -v systemd-analyze >/dev/null; then out=$(systemd-analyze verify --man=no "$stage/usr/lib/systemd/system/omamobile-fp.service" 2>&1 || true) out=$(grep -v -e 'not executable' -e 'No such file' -e 'is not a regular file' -e '^$' <<<"$out" || true) diff --git a/packages/omamobile-fingerprint/test/preflight b/packages/omamobile-fingerprint/test/preflight index 7d6498056..cbbbbe6e9 100755 --- a/packages/omamobile-fingerprint/test/preflight +++ b/packages/omamobile-fingerprint/test/preflight @@ -5,15 +5,18 @@ # contents as plain files, debugfs replaced by a stub that "dumps" from a # directory standing in for persist's file system. Nothing real is read. # -# no consent -> refused, nothing copied -# consent -> mfg_data and persist:/ss/{0,nsp} copied, hashed +# a first start -> mfg_data and persist:/ss/{0,nsp} copied, hashed +# an existing mfg_data.img -> adopted only if it matches the partition # a second start -> refused until a reboot (the /run marker) # the TDP copy missing -> refused (and never quietly recreated) # no /ss/0 in persist -> refused # the TDP copy changed -> refused # persist:/ss/0 changed -> refused # a writable partition -> refused -# existing secure storage -> allowed without the record (bring-up phones) +# hand-made copies -> the TDP copy checked against persist:/ss/0 +# a start that never ran -> the next boot skips once, the one after starts +# the path overrides -> ignored without OMAMOBILE_FP_TEST=1 +# the inner start -> refused without this boot's preflight token # the 9a without tdp.img -> refused set -euo pipefail cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." @@ -37,6 +40,7 @@ phone() { head -c 65536 /dev/urandom > "$p/dev/sda6" head -c 4096 /dev/urandom > "$p/persistfs/ss/0" echo "nsp from stock" > "$p/persistfs/ss/nsp" + echo boot-1 > "$p/boot_id" : > "$p/mounts" # debugfs -R "dump -p SRC DST" DEV: copy from persistfs, and log the call cat > "$p/bin/debugfs" < "$t/out" 2>&1 } -consent() { printf 'CONSENT=%s\nCONSENT_SOURCE=install-acknowledgement\nCONSENT_DATE=2026-11-02\n' "$1" > "$t/p/etc/fingerprint.conf"; } +# A reboot: a new boot id, /run emptied, and the stack reached "running" +# (which clears the pending marker) +newboot() { rm -rf "$t/p/run"; mkdir -p "$t/p/run"; rm -f "$S/start-pending"; head -c 8 /dev/urandom | od -An -tx1 | tr -d ' \n' > "$t/p/boot_id"; } marker=$t/p/run/omamobile-fp/storageproxyd-started S=$t/p/state -# No consent: no file, CONSENT=no, a key that only looks like it phone -pf && fail "no consent file: refused" -grep -c 'no consent' "$t/out" >/dev/null || { cat "$t/out"; fail "says why (no consent)"; } -[[ ! -e $S/persist-ss/0 && ! -e $S/mfg_data.img && ! -e $marker ]] || fail "nothing is copied or marked without consent" -consent no; pf && fail "CONSENT=no: refused" -printf 'CONSENT=yes # later\n' > "$t/p/etc/fingerprint.conf"; pf && fail "only an exact CONSENT=yes counts" -printf 'FINGERPRINT=yes\n' > "$t/p/etc/fingerprint.conf"; pf && fail "another key is not consent" -[[ ! -e $marker && ! -e $t/p/debugfs.log ]] || fail "persist is not even read without consent" -pass "no consent: refused, nothing read, copied or marked" - -# Consent: the copies are made, hashed and recorded; the marker is set -consent yes -pf || { cat "$t/out"; fail "consent: preflight passes"; } +# A first start: the copies are made, hashed and recorded; the markers are set +pf || { cat "$t/out"; fail "a first start passes preflight"; } cmp -s "$S/persist-ss/0" "$t/p/persistfs/ss/0" || fail "persist:/ss/0 copied" cmp -s "$S/persist-ss/nsp" "$t/p/persistfs/ss/nsp" || fail "persist:/ss/nsp copied" cmp -s "$S/mfg_data.img" "$t/p/dev/sda6" || fail "mfg_data copied" @@ -87,70 +82,104 @@ done [[ -e $marker ]] || fail "the once-per-boot marker is set" grep -c 'dump -p /ss/0 ' "$t/p/debugfs.log" >/dev/null || fail "persist is read with debugfs" grep -v -c 'debugfs -R dump -p ' "$t/p/debugfs.log" >/dev/null && fail "debugfs only dumps (no -w, no other request)" -pass "consent: mfg_data and persist:/ss copied read-only and their hashes recorded" +grep -c ' token [0-9a-f]\{32\}$' "$marker" >/dev/null || fail "the marker carries the token for the inner start" +[[ $(stat -c %a "$marker") == 600 ]] || fail "the marker (and its token) is root's only" +[[ $(cut -d' ' -f1 "$S/start-pending") == boot-1 ]] || fail "the start is pending until it runs" +pass "a first start: mfg_data and persist:/ss copied read-only and their hashes recorded" # A second start in the same boot pf && fail "a second start in the same boot is refused" grep -c 'Reboot' "$t/out" >/dev/null || { cat "$t/out"; fail "says to reboot"; } -rm -f "$marker" # the reboot +newboot pf || { cat "$t/out"; fail "after a reboot it starts again"; } pass "one storage proxy per boot: a second start is refused until a reboot" # The TDP copy removed by hand: refused, not recreated -rm -f "$marker" "$S/persist-ss/0" +newboot; rm -f "$S/persist-ss/0" pf && fail "a missing TDP copy is refused" grep -c 'no TDP copy' "$t/out" >/dev/null || { cat "$t/out"; fail "says the TDP copy is missing"; } [[ ! -e $S/persist-ss/0 && ! -e $marker ]] || fail "the TDP copy is never quietly recreated" pass "a missing TDP copy: refused, never recreated behind the record" # persist without /ss/0 on a new install -phone; consent yes; rm -f "$t/p/persistfs/ss/0" +phone; rm -f "$t/p/persistfs/ss/0" pf && fail "no /ss/0 in persist: refused" [[ ! -e $S/provenance && ! -e $marker ]] || fail "nothing recorded without a TDP copy" pass "persist without /ss/0: refused, no TDP copy, no storage start" # The TDP copy changed after the record (Linux wrote TDP) -phone; consent yes; pf || fail "setup" -rm -f "$marker"; echo x >> "$S/persist-ss/0" +phone; pf || fail "setup" +newboot; echo x >> "$S/persist-ss/0" pf && fail "a changed TDP copy is refused" grep -c 'TDP copy changed' "$t/out" >/dev/null || { cat "$t/out"; fail "says the TDP copy changed"; } pass "the TDP copy changed since the record: refused" # persist:/ss/0 changed under the copy (a stock boot) -phone; consent yes; pf || fail "setup" -rm -f "$marker"; echo x >> "$t/p/persistfs/ss/0" +phone; pf || fail "setup" +newboot; echo x >> "$t/p/persistfs/ss/0" pf && fail "a changed persist:/ss/0 is refused" grep -c 'persist:/ss/0 changed' "$t/out" >/dev/null || { cat "$t/out"; fail "says persist:/ss/0 changed"; } pass "persist:/ss/0 changed since the copy: refused" # The storage guard: a writable or read-write mounted partition -phone; consent yes; echo 0 > "$t/p/sys/sda5/ro" +phone; echo 0 > "$t/p/sys/sda5/ro" pf && fail "persist ro=0: refused" grep -c "not read-only" "$t/out" >/dev/null || { cat "$t/out"; fail "says persist is not read-only"; } -phone; consent yes; echo 0 > "$t/p/sys/sda6/ro" +phone; echo 0 > "$t/p/sys/sda6/ro" pf && fail "mfg_data ro=0: refused" -phone; consent yes; echo "$t/p/dev/sda5 /mnt ext4 rw,relatime 0 0" > "$t/p/mounts" +phone; echo "$t/p/dev/sda5 /mnt ext4 rw,relatime 0 0" > "$t/p/mounts" pf && fail "persist mounted read-write: refused" grep -c "mounted read-write" "$t/out" >/dev/null || { cat "$t/out"; fail "says persist is mounted read-write"; } [[ ! -e $S/mfg_data.img && ! -e $S/persist-ss/0 ]] || fail "nothing copied from an unguarded partition" pass "a writable or read-write mounted partition: refused, nothing copied" -# A bring-up phone: secure storage already there, copies by hand, no record +# Hand-made copies, no record: the TDP copy is checked, mfg_data compared phone -mkdir -p "$S/data/vendor/ss" "$S/persist-ss" -head -c 1024 /dev/urandom > "$S/data/vendor/ss/0" +mkdir -p "$S/persist-ss" cp "$t/p/persistfs/ss/0" "$S/persist-ss/0"; cp "$t/p/dev/sda6" "$S/mfg_data.img" -pf || { cat "$t/out"; fail "existing secure storage starts without a consent record"; } -[[ -f $S/provenance ]] || fail "the hand-made TDP copy is checked and recorded" +pf || { cat "$t/out"; fail "hand-made copies matching the partitions are adopted"; } +grep -c 'existing mfg_data.img matches' "$t/out" >/dev/null || fail "a matching mfg_data.img is adopted" phone -mkdir -p "$S/data/vendor/ss" "$S/persist-ss" -head -c 1024 /dev/urandom > "$S/data/vendor/ss/0" +mkdir -p "$S/persist-ss" +cp "$t/p/persistfs/ss/0" "$S/persist-ss/0"; echo stale > "$S/mfg_data.img" +pf || { cat "$t/out"; fail "a stale mfg_data.img doesn't stop the start"; } +cmp -s "$S/mfg_data.img" "$t/p/dev/sda6" || fail "a stale mfg_data.img is copied again from the partition" +ls "$S"/mfg_data.img.before-provision.* >/dev/null 2>&1 || fail "the stale one is moved aside, not deleted" +phone +mkdir -p "$S/persist-ss" echo other > "$S/persist-ss/0" pf && fail "a hand-made TDP copy that differs from persist:/ss/0 is refused" -pass "bring-up phones: existing secure storage needs no record; the TDP copy is still checked" +grep -c 'differs from persist:/ss/0' "$t/out" >/dev/null || { cat "$t/out"; fail "provision is the check that refuses it"; } +pass "hand-made copies: TDP checked against persist:/ss/0, mfg_data adopted only if it matches" + +# A start that never got running (Trusty halted): the next boot skips once +phone; pf || fail "setup" +rm -rf "$t/p/run"; echo boot-2 > "$t/p/boot_id" # a reboot; still pending +pf && fail "the boot after a start that never ran skips fingerprint" +grep -c 'never got running' "$t/out" >/dev/null || { cat "$t/out"; fail "says why it skips"; } +[[ ! -e $marker ]] || fail "a skipped boot starts no proxy" +pf || { cat "$t/out"; fail "the boot after it tries again (the pending marker went)"; } +pass "a start that never got running: the next boot skips once, then it starts again" + +# The path overrides only count in the test mode +phone +TESTMODE=0 pf && fail "without OMAMOBILE_FP_TEST=1 the fake tree is ignored" +[[ ! -e $marker && ! -e $S/provenance ]] || fail "the overrides redirected nothing outside the test mode" +pass "the partitions' and markers' path overrides need OMAMOBILE_FP_TEST=1" + +# The inner start needs this boot's preflight token +phone; pf || fail "setup" +for tok in "" wrong none; do + if PATH=$t/p/bin:$PATH OMAMOBILE_FP_TEST=1 OMAMOBILE_FP_RUN=$t/p/run/omamobile-fp OMAMOBILE_FP_STATE=$S \ + OMAMOBILE_FP_IN_NS=1 OMAMOBILE_FP_TOKEN=$tok "$RUNNER" start storage > "$t/out" 2>&1; then + fail "the inner start with token '$tok' is refused" + fi + grep -c "only after this boot's preflight" "$t/out" >/dev/null || { cat "$t/out"; fail "says why (token '$tok')"; } +done +pass "OMAMOBILE_FP_IN_NS=1 can't skip preflight: the inner start needs its token" # The 9a (mapped stores): no tdp.img, no TDP -phone; consent yes +phone DEV=tegu pf && fail "tegu without tdp.img: refused" mkdir -p "$S"; head -c 512 /dev/urandom > "$S/tdp.img" DEV=tegu pf || { cat "$t/out"; fail "tegu with tdp.img passes"; } diff --git a/packages/omamobile-fingerprint/vendor/systemd/system/omamobile-fp.service b/packages/omamobile-fingerprint/vendor/systemd/system/omamobile-fp.service index 63b59f1e1..988e64481 100644 --- a/packages/omamobile-fingerprint/vendor/systemd/system/omamobile-fp.service +++ b/packages/omamobile-fingerprint/vendor/systemd/system/omamobile-fp.service @@ -1,10 +1,11 @@ # SPDX-License-Identifier: MIT # Google's fingerprint HAL, Trusty's storage proxy, KeyMint and Gatekeeper in # a minimal chroot, plus omamobile-fp-bridge, which fprintd's omamobile_udfps -# driver talks to (device/cheetah/FINGERPRINT-PLAN.md). Not enabled by the -# package: omamobile-firstboot enables it on a phone whose owner acknowledged -# the secure-storage write at install time (/etc/omamobile/fingerprint.conf), -# and the runner refuses a first storage start without that record. +# driver talks to (device/cheetah/FINGERPRINT-PLAN.md). Enabled by the +# package (a vendor wants link) and inert until tools/phone-provision has +# pushed Google's files (the conditions below). Before storageproxyd the +# runner makes read-only copies of mfg_data and persist:/ss and refuses to +# start without the TDP copy or once it, or persist:/ss/0, changed. # # One start per boot. Trusty keeps its storage state until a reboot, and a # storage proxy stopped and started again in the same boot crashed Trusty's From 59581a73a0ff8c005f6213971b829dd34d2388c3 Mon Sep 17 00:00:00 2001 From: Derek Ross Date: Mon, 2 Nov 2026 18:34:27 -0500 Subject: [PATCH 10/15] install-phone, omamobile-firstboot: no fingerprint acknowledgement after all Fingerprint now works out of the box without a consent record (the maintainer's decision, 2026-11-02): the installer's warning loses the fingerprint paragraph and --no-fingerprint, firstboot.conf gains no FINGERPRINT/ACK_DATE, and firstboot no longer writes fingerprint.conf or enables the unit (omamobile-fingerprint enables it itself). Both are back to main's, so a new installer and an older root image stay compatible, and the firstboot bump to 0.1.4 is dropped. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BeEcdVeSfyLCbijF8XQF1d --- .../bin/omamobile-firstboot | 58 ++----------------- packages/omamobile-firstboot/test/all | 32 ---------- packages/omamobile-firstboot/version | 2 +- tests/install-phone | 37 ------------ tools/install-phone | 45 +------------- 5 files changed, 7 insertions(+), 167 deletions(-) diff --git a/packages/omamobile-firstboot/bin/omamobile-firstboot b/packages/omamobile-firstboot/bin/omamobile-firstboot index 0f81f4e2f..39f4ea018 100755 --- a/packages/omamobile-firstboot/bin/omamobile-firstboot +++ b/packages/omamobile-firstboot/bin/omamobile-firstboot @@ -24,11 +24,7 @@ # PIN or password exists, which it does here); # 9. Omarchy's user setup (omarchy-provision-user), then # omamobile-setup-user, as the user; -# 10. fingerprint, when the owner acknowledged its secure-storage write at -# install time (FINGERPRINT=yes): /etc/omamobile/fingerprint.conf, the -# record omamobile-fp-chroot requires, and omamobile-fp enabled (it -# starts once tools/phone-provision has added Google's files); -# 11. deletes firstboot.conf. +# 10. deletes firstboot.conf. # # Every step is idempotent, so a failed run can simply run again (the unit # reruns at the next boot while firstboot.conf exists). The log is @@ -52,12 +48,6 @@ # WIFI_SSID optional; WIFI_PSK with it (none for an open network) # CREDENTIAL pin or password: how the lock screen asks (default pin) # FULL_NAME, EMAIL optional; git identity, as Omarchy's installer asks -# FINGERPRINT yes or no: yes records the installer's acknowledgement of -# fingerprint's secure-storage write (typing the codename -# after its warning). Missing (an older installer) is no, -# never consent -# ACK_DATE the acknowledgement's date, YYYY-MM-DD (UTC); required -# with FINGERPRINT=yes set -euo pipefail # Tests run the whole thing against a scratch root and fake commands. @@ -113,7 +103,7 @@ parse() { [[ $value != *[$'\x01'-$'\x1f\x7f']* ]] || die "$file:$n: $key has control characters" case $key in SSH_KEY) SSH_KEYS+=("$value") ;; - USERNAME|PASSWORD_HASH|HOSTNAME|TIMEZONE|WIFI_SSID|WIFI_PSK|CREDENTIAL|FULL_NAME|EMAIL|FINGERPRINT|ACK_DATE) + USERNAME|PASSWORD_HASH|HOSTNAME|TIMEZONE|WIFI_SSID|WIFI_PSK|CREDENTIAL|FULL_NAME|EMAIL) [[ -z ${C[$key]+x} ]] || die "$file:$n: $key given twice" C[$key]=$value ;; *) die "$file:$n: unknown key $key" ;; @@ -160,14 +150,6 @@ validate() { [[ ${C[CREDENTIAL]} =~ ^(pin|password)$ ]] || die "CREDENTIAL must be pin or password" [[ ${C[FULL_NAME]:-} != *[:,]* ]] || die "FULL_NAME can't contain : or ," [[ -z ${C[EMAIL]:-} || ${C[EMAIL]} =~ ^[^[:space:]@]+@[^[:space:]@]+$ ]] || die "EMAIL '${C[EMAIL]}' is not an address" - # A missing FINGERPRINT is no: only an explicit acknowledgement is consent - C[FINGERPRINT]=${C[FINGERPRINT]:-no} - [[ ${C[FINGERPRINT]} =~ ^(yes|no)$ ]] || die "FINGERPRINT must be yes or no" - if [[ ${C[FINGERPRINT]} == yes ]]; then - [[ ${C[ACK_DATE]:-} =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ ]] || die "FINGERPRINT=yes needs ACK_DATE=YYYY-MM-DD (the acknowledgement's date)" - elif [[ -n ${C[ACK_DATE]+x} ]]; then - die "ACK_DATE without FINGERPRINT=yes" - fi } summary() { @@ -181,11 +163,6 @@ summary() { echo "wi-fi: none" fi [[ -n ${C[FULL_NAME]:-}${C[EMAIL]:-} ]] && echo "git: ${C[FULL_NAME]:-} <${C[EMAIL]:-}>" - if [[ ${C[FINGERPRINT]} == yes ]]; then - echo "fingerprint: on (secure-storage write acknowledged at install, ${C[ACK_DATE]})" - else - echo "fingerprint: off" - fi return 0 } @@ -213,9 +190,8 @@ U=${C[USERNAME]} WARNINGS=() FATAL=0 # step NAME FUNCTION: run one step, log its result, keep going on failure. -# Essential steps (the account, the password, SSH, the login, the -# fingerprint record) keep firstboot.conf in place when they fail, so the -# next boot tries again. +# Essential steps (the account, the password, SSH, the login) keep +# firstboot.conf in place when they fail, so the next boot tries again. step() { local name=$1 essential=$2 fn=$3 status echo "--- $name" @@ -482,31 +458,6 @@ s_user_setup() { return $failed } -# The owner acknowledged fingerprint's secure-storage write in the installer -# (FINGERPRINT=yes): record it where omamobile-fp-chroot looks before its -# first storage start, and enable the service. The unit stays inert until -# tools/phone-provision has pushed Google's files (its ConditionPathExists), -# then starts at the next boot. Nothing is started here. -s_fingerprint() { - [[ ${C[FINGERPRINT]} == yes ]] || { echo " off (no acknowledgement in firstboot.conf)"; return 0; } - mkdir -p "$ROOT/etc/omamobile" - { - echo "# Written by omamobile-firstboot from the installer's acknowledgement:" - echo "# the owner typed the codename after the warning that fingerprint's first" - echo "# start writes Trusty's secure storage. omamobile-fp-chroot requires it." - echo "CONSENT=yes" - echo "CONSENT_SOURCE=install-acknowledgement" - echo "CONSENT_DATE=${C[ACK_DATE]}" - } > "$ROOT/etc/omamobile/fingerprint.conf.new" - chmod 644 "$ROOT/etc/omamobile/fingerprint.conf.new" - mv -f "$ROOT/etc/omamobile/fingerprint.conf.new" "$ROOT/etc/omamobile/fingerprint.conf" - if [[ -f $ROOT/usr/lib/systemd/system/omamobile-fp.service ]]; then - systemctl enable omamobile-fp.service - else - echo " recorded; omamobile-fp.service isn't installed, so nothing to enable" - fi -} - step "pacman keyring" optional s_keyring step "hostname, time zone, locale" optional s_identity step "user ${U}" essential s_user @@ -517,7 +468,6 @@ step "services and firewall" essential s_services step "Wi-Fi" optional s_wifi step "login" essential s_login step "user setup" optional s_user_setup -step "fingerprint" essential s_fingerprint if ((FATAL)); then echo "=== firstboot incomplete: ${WARNINGS[*]}; firstboot.conf kept, the next boot tries again ===" diff --git a/packages/omamobile-firstboot/test/all b/packages/omamobile-firstboot/test/all index 789b32279..403030cf7 100755 --- a/packages/omamobile-firstboot/test/all +++ b/packages/omamobile-firstboot/test/all @@ -109,17 +109,7 @@ good | sed 's/^FULL_NAME=.*/FULL_NAME=a:b/' | refuse "a colon in the full name" { good; echo 'USERNAME=bob'; } | refuse "a key given twice" { good; echo 'not a line'; } | refuse "a line that isn't KEY=value" { good; printf 'EMAIL=a@b\x07c\n'; } | sed '/^EMAIL=alice/d' | refuse "a control character" -good | sed 's/^CREDENTIAL=.*/&\nFINGERPRINT=maybe/' | refuse "FINGERPRINT that is neither yes nor no" -good | sed 's/^CREDENTIAL=.*/&\nFINGERPRINT=yes/' | refuse "FINGERPRINT=yes without ACK_DATE" -good | sed 's/^CREDENTIAL=.*/&\nFINGERPRINT=yes\nACK_DATE=yesterday/' | refuse "an ACK_DATE that isn't a date" -good | sed 's/^CREDENTIAL=.*/&\nACK_DATE=2026-11-02/' | refuse "ACK_DATE without FINGERPRINT=yes" pass "--check refuses bad confs" -out=$(check "$t/good.conf") -grep -qx 'fingerprint: off' <<<"$out" || fail "no FINGERPRINT key means fingerprint off" -good | sed 's/^CREDENTIAL=.*/&\nFINGERPRINT=yes\nACK_DATE=2026-11-02/' > "$t/fp.conf" -out=$(check "$t/fp.conf") || fail "FINGERPRINT=yes with ACK_DATE passes: $out" -grep -q '^fingerprint: on .*2026-11-02' <<<"$out" || fail "--check reports the acknowledgement" -pass "--check: fingerprint only with an explicit, dated acknowledgement" # A value is data: a $(...) in it is never run mark=$t/ran @@ -219,28 +209,6 @@ grep -q '^clock-set' "$CALLS" && fail "no keyrings means no clock adjustment" grep -q '^pacman-key --populate' "$CALLS" || fail "key setup still runs without a floor" pass "missing keyrings leave the clock alone" -# Fingerprint: no key, no record and nothing enabled; the acknowledgement -# writes the consent record and enables the unit (inert until provisioned) -[[ ! -e $R/etc/omamobile/fingerprint.conf ]] || fail "no FINGERPRINT key: no consent record" -grep -q 'omamobile-fp' "$CALLS" && fail "no FINGERPRINT key: omamobile-fp isn't enabled" -mkdir -p "$R/usr/lib/systemd/system"; : > "$R/usr/lib/systemd/system/omamobile-fp.service" -: > "$CALLS" -good | sed 's/^CREDENTIAL=.*/&\nFINGERPRINT=no/' > "$R/etc/omamobile/firstboot.conf" -run || { cat "$t/run.out"; fail "FINGERPRINT=no runs"; } -[[ ! -e $R/etc/omamobile/fingerprint.conf ]] || fail "FINGERPRINT=no: no consent record" -grep -q 'omamobile-fp' "$CALLS" && fail "FINGERPRINT=no: omamobile-fp isn't enabled" -: > "$CALLS" -good | sed 's/^CREDENTIAL=.*/&\nFINGERPRINT=yes\nACK_DATE=2026-11-02/' > "$R/etc/omamobile/firstboot.conf" -run || { cat "$t/run.out"; fail "FINGERPRINT=yes runs"; } -printf '%s\n' CONSENT=yes CONSENT_SOURCE=install-acknowledgement CONSENT_DATE=2026-11-02 | - cmp -s - <(grep -v '^#' "$R/etc/omamobile/fingerprint.conf") || fail "the consent record" -[[ $(stat -c %a "$R/etc/omamobile/fingerprint.conf") == 644 ]] || fail "the consent record is readable (nothing secret in it)" -grep -qx 'systemctl enable omamobile-fp.service' "$CALLS" || fail "the acknowledgement enables omamobile-fp" -grep -q 'systemctl \(start\|restart\) omamobile-fp' "$CALLS" && fail "firstboot never starts omamobile-fp" -[[ ! -e $R/etc/omamobile/firstboot.conf ]] || fail "the conf is deleted after the run" -rm -f "$R/etc/omamobile/fingerprint.conf" "$R/usr/lib/systemd/system/omamobile-fp.service" -pass "fingerprint: the acknowledgement becomes the consent record and an enabled (not started) unit; none without it" - # An essential step failing keeps the conf (minus the Wi-Fi secret) for the next boot rm -f "$R/var/lib/omamobile/firstboot/user" sed -i '/^alice:/d' "$R/etc/passwd" diff --git a/packages/omamobile-firstboot/version b/packages/omamobile-firstboot/version index 845639eef..b1e80bb24 100644 --- a/packages/omamobile-firstboot/version +++ b/packages/omamobile-firstboot/version @@ -1 +1 @@ -0.1.4 +0.1.3 diff --git a/tests/install-phone b/tests/install-phone index 5493f30ef..78a3c1e26 100755 --- a/tests/install-phone +++ b/tests/install-phone @@ -150,43 +150,6 @@ OMAMOBILE_FIRSTBOOT_ROOT=$t/fbroot "$SRC/packages/omamobile-firstboot/bin/omamob debugfs -R 'stat /etc/omamobile/boot-update.conf' "$flashed" 2>/dev/null | grep -q 'User: 0 Group: 0' || fail "boot-update.conf belongs to root" pass "the image copy gets a root-only firstboot.conf (hash, not password) and root's key, which firstboot accepts" -# Fingerprint: the warning before the codename names the secure-storage -# write, and the typed codename is recorded as the acknowledgement -flashed_conf() { - local f=$t/userdata.flashed - if command -v simg2img >/dev/null && [[ $(head -c4 "$f" | od -An -tx1 | tr -d ' ') == 3aff26ed ]]; then - simg2img "$f" "$t/flashed.img"; f=$t/flashed.img - fi - debugfs -R 'cat /etc/omamobile/firstboot.conf' "$f" 2>/dev/null -} -grep -q '^FINGERPRINT=\|^ACK_DATE=' <<<"$conf" && fail "a device without omamobile-fingerprint gets no FINGERPRINT line" -grep -q 'secure storage' "$t/out" && fail "a device without omamobile-fingerprint shows no fingerprint warning" -{ descriptor; echo 'ROOTFS_PACKAGES="omamobile-audio omamobile-fingerprint omamobile-modem"'; } > "$R/device/testdev/device.conf" -install || { cat "$t/out"; fail "a full run with fingerprint succeeds"; } -conf=$(flashed_conf) -grep -qx 'FINGERPRINT=yes' <<<"$conf" || fail "the acknowledgement is recorded as FINGERPRINT=yes" -grep -qx "ACK_DATE=$(date -u +%Y-%m-%d)" <<<"$conf" || fail "and dated (UTC)" -warn=$(grep -n 'writes the$' "$t/out" | head -1 | cut -d: -f1) -prompt=$(grep -n "Type the phone's codename" "$t/out" | head -1 | cut -d: -f1) -[[ -n $warn && -n $prompt ]] && ((warn < prompt)) || fail "the fingerprint warning comes before the codename is typed" -for words in "secure storage" "can't be undone" "factory reset" "persist" "mfg_data" "Titan M2" "enroll your fingers again"; do - grep -qF "$words" "$t/out" || fail "the fingerprint warning says: $words" -done -grep -q 'fingerprint: on' "$t/out" || fail "the plan shows fingerprint on" -printf '%s\n' "$conf" > "$t/fb.conf" -OMAMOBILE_FIRSTBOOT_ROOT=$t/fbroot "$SRC/packages/omamobile-firstboot/bin/omamobile-firstboot" --check "$t/fb.conf" > "$t/fb.out" || - fail "omamobile-firstboot accepts the acknowledgement" -grep -q '^fingerprint: on' "$t/fb.out" || fail "firstboot reads the acknowledgement" -install --no-fingerprint || { cat "$t/out"; fail "--no-fingerprint runs"; } -conf=$(flashed_conf) -grep -qx 'FINGERPRINT=no' <<<"$conf" || fail "--no-fingerprint records FINGERPRINT=no" -grep -q '^ACK_DATE=' <<<"$conf" && fail "--no-fingerprint records no acknowledgement" -grep -q 'secure storage' "$t/out" && fail "--no-fingerprint shows no fingerprint warning" -CONFIRM=cheetah install && fail "a wrong confirmation is refused with fingerprint on" -[[ -z $(flashing_calls) ]] || fail "nothing is flashed (and no acknowledgement leaves the laptop) without the codename" -descriptor > "$R/device/testdev/device.conf" -pass "fingerprint: the warning names the secure-storage write before the codename; the codename is recorded as FINGERPRINT=yes and ACK_DATE" - refuse() { local why=$1; shift if install "$@"; then cat "$t/out"; fail "refuses $why"; fi diff --git a/tools/install-phone b/tools/install-phone index b9a334351..0adf5040b 100755 --- a/tools/install-phone +++ b/tools/install-phone @@ -53,17 +53,6 @@ # slot B is refused, since that is where stock # Android runs after a system update # --unsigned accept a bundle without SHA256SUMS.sig (development) -# --no-fingerprint developers: leave fingerprint off (FINGERPRINT=no); -# the phone's runner then refuses to write Trusty's -# secure storage -# -# Fingerprint (a device whose ROOTFS_PACKAGES has omamobile-fingerprint): the -# warning before the codename names the secure-storage write that its first -# start makes, and typing the codename acknowledges it with the wipe. That -# acknowledgement is recorded as FINGERPRINT=yes and ACK_DATE (UTC) in -# firstboot.conf; omamobile-firstboot turns it into -# /etc/omamobile/fingerprint.conf and enables the service -# (device/cheetah/FINGERPRINT-PLAN.md F19). # # Answers are read from standard input, so they can be piped for tests. set -euo pipefail @@ -82,11 +71,10 @@ say() { printf '\e[1m==> %s\e[0m\n' "$*"; } note() { printf ' %s\n' "$*"; } die() { printf '\e[31merror:\e[0m %s\n' "$*" >&2; exit 1; } -dry=0 device="" images="" rootfs="" work="" slots_match="" unsigned=0 reinstall=0 no_fingerprint=0 +dry=0 device="" images="" rootfs="" work="" slots_match="" unsigned=0 reinstall=0 while (($#)); do case $1 in --dry-run) dry=1 ;; - --no-fingerprint) no_fingerprint=1 ;; --device) device=${2:?}; shift ;; --images) images=${2:?}; shift ;; --rootfs) rootfs=${2:?}; shift ;; @@ -94,7 +82,7 @@ while (($#)); do --bootloader-slots-match) slots_match=${2:?}; shift ;; --reinstall) reinstall=1 ;; --unsigned) unsigned=1 ;; - -h|--help) sed -n '3,/^# Answers are read/p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0 ;; + -h|--help) sed -n '3,50p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0 ;; *) die "unknown argument $1 (see --help)" ;; esac shift @@ -496,16 +484,6 @@ while true; do done ssh_key=$(head -1 "$key_file") -# Fingerprint: on for a device that ships it, unless --no-fingerprint. The -# acknowledgement is the codename typed after the warning below; the file -# carrying it reaches the phone only after that. -fingerprint="" -if [[ " ${D[ROOTFS_PACKAGES]:-} " == *" omamobile-fingerprint "* ]]; then - fingerprint=yes - ((no_fingerprint)) && fingerprint=no -fi -ack_date=$(date -u +%Y-%m-%d) - # --- A local copy of the root image, with the owner's first-boot file ------- work=${work:-${XDG_CACHE_HOME:-$HOME/.cache}/omamobile-install} mkdir -p "$work" @@ -531,11 +509,6 @@ trap cleanup EXIT echo "WIFI_SSID=$wifi_ssid" [[ -n $wifi_psk ]] && echo "WIFI_PSK=$wifi_psk" fi - if [[ -n $fingerprint ]]; then - echo "FINGERPRINT=$fingerprint" - [[ $fingerprint == yes ]] && echo "ACK_DATE=$ack_date" - fi - true } > "$conf_file" printf '%s\n' "$ssh_key" > "$keys_file" printf '%s\n' "# Written by install-phone: a release install takes kernel updates through" \ @@ -609,10 +582,6 @@ note "user: $username ($credential), host $hostname, time zone $timezone" note "Wi-Fi: ${wifi_ssid:-none}" note "SSH key: ${ssh_key:0:40}... (root and $username)" note "root image: $(basename "$rootfs")" -case $fingerprint in - yes) note "fingerprint: on from the first start (see below)" ;; - no) note "fingerprint: off (--no-fingerprint)" ;; -esac echo echo "These commands, and only these, will run:" for p in $BOOT_IMAGES; do echo " fastboot flash ${p}_b $images/$p.img"; done @@ -624,16 +593,6 @@ echo "userdata will be ERASED: stock Android's data is lost, and stock Android o echo "slot A will need a factory reset if you ever boot it again. Slot A itself," echo "the bootloader, radio, persist, efs, modem and devinfo are not touched." echo -if [[ $fingerprint == yes ]]; then - echo "Fingerprint unlock is on from the first start. Its first start writes the" - echo "phone's secure storage (Trusty's area in the UFS RPMB). That can't be undone," - echo "but it is the same kind of write Android makes at every factory reset." - echo "Nothing is written to persist, the factory calibration (mfg_data), the" - echo "Titan M2 security chip or Android's slot A. Going back to Android works as" - echo "usual: Android starts like a new phone after its factory reset, and you" - echo "enroll your fingers again there." - echo -fi answer=$(ask "Type the phone's codename ($CODENAME) to go ahead") [[ $answer == "$CODENAME" ]] || die "not confirmed; nothing was written" From 4f2ecc20438f72610f17c9775ba5daf04bdadbd0 Mon Sep 17 00:00:00 2001 From: Derek Ross Date: Mon, 2 Nov 2026 18:35:02 -0500 Subject: [PATCH 11/15] omamobile-shell 0.2.89: onboarding says when fingerprint is unavailable, not "after the firmware" When the sensor isn't ready, setup now tells the three cases apart: the unit failed or was refused on this boot ("unavailable on this boot", with the journal to read, and the PIN unlocks), Google's files aren't there yet ("ready once your phone's firmware is added"), or it is still starting (offered at the next login). Before, a refused unit was blamed on missing firmware. Renumbered from 0.2.85: main is at 0.2.86, #362 holds 0.2.88, and 0.2.87 is left for #357. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BeEcdVeSfyLCbijF8XQF1d --- .../omamobile-shell/bin/omamobile-onboarding | 9 +++++++-- .../test/onboarding-fingerprint.sh | 16 +++++++++++----- packages/omamobile-shell/version | 2 +- 3 files changed, 19 insertions(+), 8 deletions(-) diff --git a/packages/omamobile-shell/bin/omamobile-onboarding b/packages/omamobile-shell/bin/omamobile-onboarding index 51b0039c1..18d4511f2 100644 --- a/packages/omamobile-shell/bin/omamobile-onboarding +++ b/packages/omamobile-shell/bin/omamobile-onboarding @@ -20,6 +20,7 @@ set -u omarchy_path=${OMARCHY_PATH:-/usr/share/omarchy} fp_runner=${OMAMOBILE_FP_RUNNER:-/usr/lib/omamobile-fp/omamobile-fp-chroot} +fp_image=${OMAMOBILE_FP_IMAGE:-/usr/lib/omamobile-fp/root} fp_offered=${XDG_STATE_HOME:-$HOME/.local/state}/omamobile/fingerprint-offered has_identity() { @@ -74,9 +75,13 @@ offer_fingerprint() { local n n=$(fp_count) if [[ -z $n ]]; then - if systemctl is-enabled --quiet omamobile-fp.service 2>/dev/null; then - echo + echo + if systemctl is-failed --quiet omamobile-fp.service 2>/dev/null; then + echo "Fingerprint unlock is unavailable on this boot (see journalctl -u omamobile-fp). Your PIN or password unlocks the phone." + elif [[ ! -d $fp_image ]]; then echo "Fingerprint unlock will be ready once your phone's firmware is added and it restarts. The phone offers it then." + else + echo "Fingerprint unlock is still starting. The phone offers it at your next login." fi return 0 fi diff --git a/packages/omamobile-shell/test/onboarding-fingerprint.sh b/packages/omamobile-shell/test/onboarding-fingerprint.sh index e76e08d59..3ff6784be 100644 --- a/packages/omamobile-shell/test/onboarding-fingerprint.sh +++ b/packages/omamobile-shell/test/onboarding-fingerprint.sh @@ -22,13 +22,13 @@ fake omamobile-set-pin 'case $1 in --type) echo PIN ;; --inner) touch "$T/pin" ; fake omamobile-fp-enroll '[[ -e $T/listing ]] && cat "$T/listing"; true' fake omarchy-shell 'echo "shell $*" >>"$T/log"' fake omarchy-notification-send 'echo "notify $*" >>"$T/log"' -fake systemctl '[[ $* == "is-enabled --quiet omamobile-fp.service" && -e $T/enabled ]]' +fake systemctl '[[ $* == "is-failed --quiet omamobile-fp.service" && -e $T/failed ]]' fake timeout 'shift; "$@"' ob() { - env -u XDG_STATE_HOME T="$t" HOME="$t/home" USER=alice OMARCHY_PATH="$t/none" OMAMOBILE_FP_RUNNER="$t/runner" \ + env -u XDG_STATE_HOME T="$t" HOME="$t/home" USER=alice OMARCHY_PATH="$t/none" OMAMOBILE_FP_RUNNER="$t/runner" OMAMOBILE_FP_IMAGE="$t/image" \ PATH="$F:/usr/bin:/bin" bash bin/omamobile-onboarding "$@" >"$t/out" 2>&1 } -reset() { rm -f "$t/pin" "$t/yes" "$t/listing" "$t/enabled" "$t/log"; rm -rf "$t/home/.local"; : >"$t/log"; } +reset() { rm -rf "$t/pin" "$t/yes" "$t/listing" "$t/failed" "$t/image" "$t/log"; rm -rf "$t/home/.local"; : >"$t/log"; } ready() { printf '{"event": "fingers", "fingers": [%s], "stages": 12, "device": "Omarchy Mobile UDFPS"}\n' "${1:-}" >"$t/listing"; } # Setup: the PIN is set, then the fingerprint is offered and taken @@ -46,9 +46,15 @@ grep -c 'Skipped' "$t/out" >/dev/null || fail "skip says where to add one later" grep -c 'summon' "$t/log" >/dev/null && fail "skip opens nothing" reset; ready '"right-index-finger"' ob --inner; grep -c 'confirm' "$t/log" >/dev/null && fail "a finger already enrolled: no offer" -reset; touch "$t/enabled" +reset ob --inner; grep -c 'confirm' "$t/log" >/dev/null && fail "a sensor not ready: no offer" -grep -c 'ready once your phone' "$t/out" >/dev/null || fail "a sensor not ready yet: setup says it comes later" +grep -c 'ready once your phone' "$t/out" >/dev/null || fail "not provisioned yet: setup says it comes after the firmware" +reset; mkdir "$t/image"; touch "$t/failed" +ob --inner; grep -c 'unavailable on this boot' "$t/out" >/dev/null || fail "a refused or failed unit: setup says unavailable, not 'after the firmware'" +grep -c 'ready once your phone' "$t/out" >/dev/null && fail "a failed unit isn't blamed on missing firmware" +reset; mkdir "$t/image" +ob --inner; grep -c 'still starting' "$t/out" >/dev/null || fail "provisioned but not up yet: offered at the next login" +reset [[ ! -e $t/home/.local/state/omamobile/fingerprint-offered ]] || fail "not ready: the offer waits for a later login" reset; ready; rm -f "$t/runner" ob --inner; grep -c 'confirm' "$t/log" >/dev/null && fail "no fingerprint stack: no offer" diff --git a/packages/omamobile-shell/version b/packages/omamobile-shell/version index ef61b8ebe..d7efa6e15 100644 --- a/packages/omamobile-shell/version +++ b/packages/omamobile-shell/version @@ -1 +1 @@ -0.2.85 +0.2.89 From 684f7518bb6bdfc8f823ccad525df1fae0996881 Mon Sep 17 00:00:00 2001 From: Derek Ross Date: Mon, 2 Nov 2026 18:36:21 -0500 Subject: [PATCH 12/15] FINGERPRINT-PLAN, AGENTS, INSTALL: fingerprint starts by default, the runner's guards keep stock's data safe MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The consent step is gone (the maintainer's decision, 2026-11-02). AGENTS' fingerprint rule now says what is true: omamobile-fp starts by default, its storageproxyd writes Trusty's TD superblocks at every boot, and the runner's guards (read-only copies, the TDP refusal, one proxy per boot) are what keep stock's persistent data safe; never write persist or mfg_data, never restart storageproxyd in a boot, never restore an old TD. FINGERPRINT-PLAN: status, the rules, F19's default-on flow and the T1 checks follow (the package enables the unit; a stop takes seconds in order; the refused restart). §4 no longer says persist is read through a read-only mount (it is debugfs), and F4 notes that the stage-by-stage starts are superseded by one proxy per boot. INSTALL and the release notes say plainly that fingerprint unlock works after provisioning, and that fingers are enrolled again after a reinstall or on Android, without claims beyond what has run. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BeEcdVeSfyLCbijF8XQF1d --- AGENTS.md | 4 +- device/cheetah/FINGERPRINT-PLAN.md | 105 ++++++++++++++-------------- device/cheetah/NOTES.md | 14 ++-- docs/DEVICES.md | 2 +- docs/INSTALL.md | 4 +- docs/release-notes/2026-11-DRAFT.md | 6 +- 6 files changed, 67 insertions(+), 68 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7e5c27c06..74bf8d8f6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,7 +7,7 @@ Omarchy Mobile runs native Omarchy (Arch Linux ARM, Hyprland, Omarchy's packages ## 1. Safety rules (non-negotiable) -- **Ask the human before every reboot, flash, `push`, overlay boot or irreversible write.** That includes RPMB writes, a first `storageproxyd` run, `devinfo` and anything under `/dev/sd*`. One recorded exception: on a phone installed with `tools/install-phone`, the owner's install-time acknowledgement (`/etc/omamobile/fingerprint.conf`, `CONSENT=yes`) is the human's go for that phone's first `storageproxyd` run (fingerprint below). The phone is real hardware with calibration data that can't be replaced, and a human has to be ready to recover it. +- **Ask the human before every reboot, flash, `push`, overlay boot or irreversible write.** That includes RPMB writes, a first `storageproxyd` run, `devinfo` and anything under `/dev/sd*`. The one exception is `omamobile-fp`'s own start at boot (fingerprint below): its storageproxyd runs by default. The phone is real hardware with calibration data that can't be replaced, and a human has to be ready to recover it. - **The phone is shared with a human. Announce anything that affects the screen or the feel of the phone before you run it**: DPMS, display modes and refresh rate, brightness, `bl_power`, haptics, the torch, the shell restarting, rotation. Otherwise they think the phone is broken, or it buzzes in their hand. - **Only slot B and `userdata` are ours.** Write only `boot_b`, `init_boot_b`, `vendor_boot_b`, `vendor_kernel_boot_b` and `dtbo_b`, and only through `bin/omamobile flash|push` or, on a phone whose `/etc/omamobile/boot-update.conf` says `AUTO_WRITE=yes` (only `tools/install-phone` writes it, for a release install, or a human by hand in an approved runbook), `linux-omamobile`'s pacman hook `omamobile-boot-update` ([RELEASES](docs/RELEASES.md) §5.3, §12 decisions 3 and 10): it writes only `_b` for the descriptor's `BOOT_IMAGES`, each found by GPT name on the main LUN, on `UFS_RW` and left `ro` 0 by the storage guard, read back by sha256, and never reboots. A development phone has no such file, so `push` stays its only writer. Never touch bootloader, radio, `devinfo`, `persist`, `efs*`, `modem*` or `vbmeta`, and never run an unsuffixed `fastboot flash`, with one exception: `userdata`, and only through `tools/install-phone` (serial pinned, codename typed, allowlist, dry run first). Slot A's stock Android is the way back. - **Qualcomm A/B phones (Pixel 4 family) keep the slot flags in GPT attributes,** so slot B can only be marked bootable by writing the partition table. That write is a narrow, named exception, never automatic: by hand, once per install of slot B's boot image, and only for a device whose entry in [CONTRIBUTING](CONTRIBUTING.md) §3.1 names the LUN, the four sectors (LBAs 1, 2, last-1 and last), the attribute bit and the CRCs it rewrites. That device's plan must also record the slot flags before and after, the rollback for a corrupted GPT, and the way back: stock restored on slot A first, or the owner's explicit acceptance of buttons-only recovery. The storage guard can't block this write, so it never runs from a service or at boot. @@ -156,7 +156,7 @@ Each entry gives the gotcha, then the reason or the fix. Details are in the link - **ACPM reads its channel table from APM SRAM, and some channels are unusable** (a type-2 buffer channel with queues in DRAM): skip them rather than failing the probe. DVFS is channel 0, PMIC 2, thermal 9. Upstream supports polling only. [ACPM-PLAN](device/cheetah/ACPM-PLAN.md) - **The regulator core turns off unused rails that have constraints about 30 s after late init:** load PMIC regulator modules after that, or make sure the rails are claimed. Since #227 the shared kernel builds `sec_acpm` in (the Pixel 9a's USB PHY needs its S2MPG14 rails at boot), so on the 7 Pro the S2MPG13 rails in the DT register before that cleanup and a `blacklist sec_acpm` does nothing; LDO9S-11S are GNSS-only, and LDO15S (`vdd_udfps`, the fingerprint sensor) and LDO12S (`vddio_cam`, camera I/O) are claimed by their drivers when those load, so the cleanup only turns off rails with no consumer yet. The fingerprint and camera starts' `modprobe sec_acpm` is a no-op there too. [GNSS-PLAN](device/cheetah/GNSS-PLAN.md) - **The AoC starts only through Trusty** (`com.android.trusty.gsa.hwmgr.aoc`). The GSA mailbox `START` leaves the A32 held. So Trusty is a dependency of audio and sensors, not just of fingerprint, and it runs at every boot on the integration kernel. -- **Fingerprint: nothing writes `persist` or the RPMB without the human's explicit go.** The first `storageproxyd` run is irreversible (an RPMB write, the same kind as an Android factory reset). Since 2026-11-02 the owner's recorded install-time acknowledgement counts as that go on their phone: `tools/install-phone`'s warning names the write, typing the codename acknowledges it, and firstboot records it in `/etc/omamobile/fingerprint.conf` and enables `omamobile-fp` (the package still ships it disabled). The runner (`omamobile-fp-chroot`, omamobile-fingerprint 0.1.14) refuses the first storage start without that record, makes the read-only copies of `mfg_data` and `persist:/ss` itself, and refuses storageproxyd without the TDP copy or when the copy or `persist:/ss/0` no longer matches its recorded hash. Every other rule stands: `persist` and `mfg_data` are never written, the TDP copy stays read-only, nothing touches the Titan M2, and on a phone without the record (set up by hand, or an agent's runbook) ask first. **One storage proxy per boot:** never stop and start `omamobile-fp` (or any storageproxyd) in the same boot; Trusty keeps its storage state until a reboot, and a restart between TD's clear and its first commit crashed Trusty's storage app (F19). Reboot instead; the runner refuses a second start. Never restore an old TD. [FINGERPRINT-PLAN](device/cheetah/FINGERPRINT-PLAN.md) F19 +- **Fingerprint: `omamobile-fp` starts by default** (omamobile-fingerprint 0.1.14 enables it; it is inert until `tools/phone-provision` has pushed Google's files). Its storageproxyd writes Trusty's TD superblocks to the RPMB at every boot, the first time like an Android factory reset. What keeps stock's persistent data safe is the runner's guards: read-only copies of `mfg_data` and `persist:/ss` (debugfs, `persist` never mounted), a refusal to start when the TDP copy is missing or differs from its recorded hash or `persist:/ss/0` changed, and one storage proxy per boot. Never write `persist` or `mfg_data`, never weaken those guards, and never stop and start `omamobile-fp` (or any storageproxyd) in the same boot: Trusty keeps its storage state until a reboot, and a restart between TD's clear and its first commit crashed Trusty's storage app (F19), so reboot instead (the runner refuses a second start). Never restore an old TD (`phone-provision --restore-td` only if no storageproxyd ran since the backup). Starting the stack by hand where it isn't running (stage starts, runbooks) is still the human's call. [FINGERPRINT-PLAN](device/cheetah/FINGERPRINT-PLAN.md) F19 - **Set the Bluetooth address only after powering the controller on:** set on a never-powered controller, the kernel withdrew the index for good. - **spi-s3c64xx with automatic chip select dropped bits between transfers before linux-omarchy-mobile#150 (merged 2026-10-31):** its FIFO flush cleared the packet count before turning the channels off, so the controller clocked a few bits with the slave still selected. A slave that restarts per chip-select cycle (touch) doesn't notice; one that streams across cycles (the 9a's GNSS core, CHPP) loses 2-6 bits per transfer, and every read lands at a different bit offset. [tegu MODEM-PLAN](device/tegu/MODEM-PLAN.md) "G3, GNSS gets a fix" - **A node without pinctrl runs on the bootloader's pins, and a pin change tested next to another fix proves nothing on its own.** The 9a's GNSS SPI has no pin group and runs at the bootloader's drive 0; raising the drive looked like it cleaned the data, but it was tested together with the SPI flush fix, and with the flush fix alone at drive 0 the data was just as clean (linux-omarchy-mobile#151 closed). Read the bank's CON/PUD/DRV in `/sys/kernel/debug/pinctrl//pins` (one controller at a time, as the gs101 note above says) before changing anything, then change one thing per boot, and check whose pins they are in the vendor tree before claiming them (gpp22 is the eSE's). [tegu MODEM-PLAN](device/tegu/MODEM-PLAN.md) "G3, GNSS gets a fix" diff --git a/device/cheetah/FINGERPRINT-PLAN.md b/device/cheetah/FINGERPRINT-PLAN.md index a44c1d745..b6de14d58 100644 --- a/device/cheetah/FINGERPRINT-PLAN.md +++ b/device/cheetah/FINGERPRINT-PLAN.md @@ -1,16 +1,15 @@ # Fingerprint plan (cheetah / gs201): fingerprint unlock on the lock screen -Status (2026-11-02): **on by default for new installs, from -omamobile-fingerprint 0.1.14 and omamobile-firstboot 0.1.4** (section 6, -F19). The installer's wipe warning names the secure-storage write, typing -the codename is the owner's consent, firstboot records it in -`/etc/omamobile/fingerprint.conf` and enables `omamobile-fp`, and the runner -makes the read-only copies of `mfg_data` and `persist:/ss` itself, refuses -storageproxyd without the consent record or the TDP copy, and runs one -storage proxy per boot. The reference phone was reinstalled on 2026-11-02 -and enrolled again by hand (F19 results, section 7). The fresh-install checks -(F19.T1-T3) haven't run yet. +Status (2026-11-02): **on by default, from omamobile-fingerprint 0.1.14** +(section 6, F19). The package enables `omamobile-fp`; it is inert until +`tools/phone-provision` has pushed Google's files and starts at the reboot +after. Before storageproxyd the runner makes the read-only copies of +`mfg_data` and `persist:/ss` itself, refuses to start without the TDP copy +or once the copy or `persist:/ss/0` differs from its recorded hash, and runs +one storage proxy per boot. The reference phone was reinstalled on +2026-11-02 and enrolled again by hand (F19 results, section 7). The +fresh-install checks (F19 T1-T3) haven't run yet. Earlier status (2026-10-19): **works, opt-in.** F3-F9 (the HAL) and the fprintd stages through F16b passed on the phone (section 7): the lock screen @@ -169,16 +168,13 @@ surprises are in F6c (what the HAL waits on) and F7 (LHBM timing). ## 4. Rules for this subsystem -- **Never write `persist` or the RPMB without the human's explicit say-so.** - The first `storageproxyd` run (F4) counts as an irreversible write. Since - 2026-11-02 the owner's recorded install-time acknowledgement counts as - that say-so on their phone: the installer's warning names the write, - typing the codename acknowledges it, and `/etc/omamobile/fingerprint.conf` - (`CONSENT=yes`, written by firstboot) records it. The runner refuses the - first storage start without that record. Anywhere else (a phone set up - by hand, an agent's runbook), ask, and record the answer here. Every later - start of `omamobile-fp.service` or `omamobile-fp-chroot start` also runs - storageproxyd: after the first run that is normal operation. +- **`omamobile-fp` starts by default** (from 0.1.14), so its first start, + which writes Trusty's TD superblock to the RPMB (the same kind of write as + an Android factory reset), happens on every new install after + provisioning. What keeps stock's persistent data safe is the runner's + guards: the read-only copies, the TDP refusal and one proxy per boot. + Starting the stack by hand on a phone where it isn't running yet (a stage + start, a runbook) is still the human's call. - `persist` is never written, and `mfg_data` neither: both are only read, and the TDP copy stays read-only (decision A, section 5). A TDP copy that changes, or a `persist:/ss/0` that no longer matches it, stops the runner @@ -191,9 +187,10 @@ surprises are in F6c (what the HAL waits on) and F7 (LHBM timing). `Restart=`. - Never restore an old TD (`tools/phone-provision --restore-td`) unless no storageproxyd ran between taking the backup and restoring it. -- `persist` and `mfg_data` are only ever read (read-only mount, `dd` - from the by-partlabel node). Never add them to the storage guard's - `UFS_RW` allowlist without the human's decision (section 5). +- `persist` and `mfg_data` are only ever read: `debugfs` dumps from + `persist` without mounting it, and `dd` from `mfg_data`, both found by + `PARTNAME`. Never add them to the storage guard's `UFS_RW` allowlist + without the human's decision (section 5). - `sg` stays blacklisted from autoload. The runner loads it, binds only the RPMB LUN's node into the chroot, and `modprobe -r sg` removes the rest. - Check the partition backups before F3 (FB, as `MODEM-PLAN.md` M0.1). @@ -374,6 +371,11 @@ mounts read-write or the storage guard complains. Rollback: `modprobe -r sg`. ### F4: secure storage (IRREVERSIBLE: the first RPMB write from Linux) +> Superseded for new runs by F19: one storage proxy per boot. The stage-by-stage +> starts below (and in F5-F9) stop and start storageproxyd in one boot, which +> crashed Trusty's storage app on 2026-11-02; run them only with a reboot +> after each stop. + **Ask the human; record the yes and the section 5 choice here first.** The staged runs use the transient unit `omamobile-fp-stage`. The package ships its own `omamobile-fp.service` (disabled, the full bridge), so @@ -1072,26 +1074,26 @@ before a wipe, with the service stopped (`systemctl stop omamobile-fp; tar -C /var/lib -cf - omamobile-fp | …` into `~/android/reference/`, mode 600), and restore it with `--restore-td`. Never restore an older one. -#### F19 on a new install: what runs by itself (omamobile-fingerprint 0.1.14, omamobile-firstboot 0.1.4) - -1. `tools/install-phone` shows the warning with the fingerprint paragraph - before the codename; the typed codename is the acknowledgement, recorded - as `FINGERPRINT=yes` and `ACK_DATE` in `firstboot.conf`. -2. Firstboot writes `/etc/omamobile/fingerprint.conf` (`CONSENT=yes`, - `CONSENT_SOURCE=install-acknowledgement`, `CONSENT_DATE`) and enables - `omamobile-fp`. The unit is skipped (`ConditionPathExists`) until - `tools/phone-provision` has pushed Google's tree. -3. At the reboot after provisioning, the runner's preflight: consent present - (or this install's TD already exists), `persist` and `mfg_data` `ro=1` - and `persist` not mounted read-write, the F19.3 copies made and hashed - into `provenance`, the TDP copy and `persist:/ss/0` both still matching - the recorded hash, and no storageproxyd earlier in this boot. Any failure - refuses before storageproxyd and leaves the unit failed; the lock uses - the PIN. -4. One session: storage, the TA, KeyMint, Gatekeeper, the HAL, the bridge. - On stop, the bridge and the HAL go first and storageproxyd last. -5. Onboarding offers "Add a fingerprint" after the PIN once the sensor is - ready (or at the first login after it is), once. +#### F19 on a new install: what runs by itself (omamobile-fingerprint 0.1.14) + +1. The package enables `omamobile-fp` (a vendor wants link), so only a + runner with these guards is ever enabled by default. The unit is skipped + (`ConditionPathExists`) until `tools/phone-provision` has pushed Google's + tree. +2. At the reboot after provisioning, the runner's preflight: no start that + never got running at the last boot (else this boot skips once), `persist` + and `mfg_data` `ro=1` and `persist` not mounted read-write, the F19.3 + copies made and hashed into `provenance` (an existing `mfg_data.img` only + if it matches the partition), the TDP copy and `persist:/ss/0` both still + matching the recorded hash, and no storageproxyd earlier in this boot. + Any failure refuses before storageproxyd and leaves the unit failed; the + lock uses the PIN. +3. One session: storage, the TA, KeyMint, Gatekeeper, the HAL, the bridge. + On stop (or a failure inside the namespace), the bridge and the HAL go + first and storageproxyd last. +4. Onboarding offers "Add a fingerprint" after the PIN once the sensor is + ready (or at the first login after it is), once; a failed unit is shown + as unavailable. A divergent TDP refuses the start instead of warning. Once Linux (or a stock boot after a slot A fallback) has written TDP, each further start @@ -1102,18 +1104,17 @@ as it was found, and costs only fingerprint (the PIN unlocks). **Fresh-install checks before calling default-on done** (the test phone; wipes are fine there): -- **T1, a new install.** The release bundle with these packages and the new - installer. Before `phone-provision`: `systemctl is-enabled omamobile-fp` - enabled, the unit skipped by its condition, `/etc/omamobile/fingerprint.conf` - present. After provisioning and the reboot: the runner's log shows the +- **T1, a new install.** The release bundle with these packages. Before + `phone-provision`: `systemctl is-enabled omamobile-fp` reads enabled, and + the unit is skipped by its condition. After provisioning and the reboot: the runner's log shows the copies and the recorded hashes (`persist-ss/0` `e0e1990d…`), Trusty's log as in F19.4, enrollment from onboarding with the "write initial superblock" - lines, and unlocking works. Then `systemctl restart omamobile-fp`: refused + lines, and unlocking works. Then `systemctl stop omamobile-fp`: the + journal shows the bridge and HAL, then KeyMint and Gatekeeper, then + storageproxyd, in a few seconds; `systemctl start omamobile-fp`: refused with "reboot"; a reboot: it starts again. A day of use, three reboots and - sleep cycles: TDP still `e0e1990d…`, F19.0 `SAME`. Negative: with - `--no-fingerprint` the unit stays disabled and `omamobile-fp-chroot - preflight` refuses (no consent); with `persist-ss/0` removed by hand the - runner refuses storageproxyd. + sleep cycles: TDP still `e0e1990d…`, F19.0 `SAME`. Negative: with `persist-ss/0` + removed by hand the runner refuses storageproxyd and doesn't recreate it. - **T2, back to stock.** `fastboot --set-active=a`, recovery, "Factory data reset"; set up Android with a PIN, enroll a finger, unlock with it, reboot twice; make a TEE-backed key; `adb logcat -b all -d | grep -iE diff --git a/device/cheetah/NOTES.md b/device/cheetah/NOTES.md index ae462f53b..a128cfb11 100644 --- a/device/cheetah/NOTES.md +++ b/device/cheetah/NOTES.md @@ -23,14 +23,12 @@ the runbook and every step: [FINGERPRINT-PLAN](FINGERPRINT-PLAN.md) F19. After a reboot, one continuous session enrolled `right-index-finger` (17:15:25) and matched it (17:15:33), with the expected "write initial superblock" lines. -- **Fingerprint is now on by default for new installs**, by the maintainer's - decision: the installer's warning names the secure-storage write and the - typed codename is the consent (firstboot records it in - `/etc/omamobile/fingerprint.conf`). The runner makes the read-only copies - itself, refuses storageproxyd without consent or the TDP copy or when TDP - changed, and runs one storage proxy per boot (no `Restart=`, a `/run` - marker, the proxy stopped last). The fresh-install checks T1-T3 are still - to run. +- **Fingerprint is now on by default**, by the maintainer's decision + (omamobile-fingerprint 0.1.14 enables `omamobile-fp`; it starts after + provisioning). The runner makes the read-only copies itself, refuses + storageproxyd without the TDP copy or when TDP changed, and runs one + storage proxy per boot (no `Restart=`, a `/run` marker, the proxy stopped + last). The fresh-install checks T1-T3 are still to run. ## 2026-11-02: a kernel update through pacman, booted and rolled back diff --git a/docs/DEVICES.md b/docs/DEVICES.md index 1f9504aee..551d59874 100644 --- a/docs/DEVICES.md +++ b/docs/DEVICES.md @@ -56,7 +56,7 @@ The status of each device, as verified on real hardware. Rows in the matrix have | NFC | works | ST54J over I2C through st-nci with our plain-NCI link, loaded at boot; neard (patched for empty Type 4 tags) reads and writes tags, and tapping a tag with a web link opens it (`omamobile-nfc-open`): writing a tag and opening its link tested on the phone (N3). Card emulation and the secure element are not used | [RADIOS-CAMERA-PLAN](../device/cheetah/RADIOS-CAMERA-PLAN.md) §3 | | Cameras | works (telephoto fixed-focus) | Ultrawide (Sony IMX386, D-PHY link 2): works end to end through our CSIS/WDMA driver and libcamera's software ISP (CAM5), basic quality (no Google ISP or tuning); a libcamera build with autofocus and low-light patches is installed, not yet evaluated (CAM5.3). Front (Samsung S5K3J1, D-PHY link 0): real images, raw and through libcamera (`cam -c1`, 30 fps, no WDMA errors; F.5-F.7, 2026-10-13). Main (Samsung S5KGN1, C-PHY link 1): 2016x1136 at 30 fps through libcamera with no WDMA errors. Telephoto (S5KGM5, C-PHY): 26 fps through libcamera, colour bars correct; its lens (SEM1215) isn't driven yet, so it stays at its resting focus: distant subjects are sharp (outdoors, 2026-10-26), close ones soft, and tap to focus does nothing. The CSIS write DMA (not the link) loses lines that arrive faster than about 400 MB/s within a line, so the sensors lengthen their lines to stay under `samsung,max-line-throughput` (360 in cheetah's DT for the main, telephoto and front cameras; the front's full 3840x2736 mode runs at 26 fps). The ultrawide (imx386) follows the same rule, so its full 4032x3016 mode streams (23 fps; one run in several still showed WDMA errors), and with 384 MiB of CMA `cam` without options runs every camera at full size (main 12 MP at 9.4 fps). The telephoto's lens (SEM1215) answers on a 950 kHz bus but holds the bus when driven longer, so the telephoto runs at fixed focus. Sensor and DC-PHY settings come from the user's own camera software (`tools/extract-camera-data`), never shipped. Since omamobile-device-cheetah 0.1.30 the camera modules load after boot (`omamobile-camera.timer`), the DMA-BUF heaps are open to the session (libcamera's software ISP), WirePlumber names them Main, Ultrawide, Telephoto and Front camera (0.1.31). The default camera app is omacam ("Camera", omamobile-apps 0.2.0; [CAMERA-APP-PLAN](CAMERA-APP-PLAN.md)): libcamera directly, zoom across the three back lenses, full-resolution photos. GNOME Snapshot is optional, named "Snapshot", for video until omacam records it; browsers and video calls use the cameras through PipeWire (`pipewire-libcamera`). Picture quality: libcamera 0.7.2-4.21 adds chroma noise reduction and defective pixel correction, and omacam 0.3.3 has Night mode and an HDR chip, bursts of raw frames aligned, merged and finished on the phone (Night: 12 frames in about 4.6 s, Q5.3 on 2026-10-21); single shots are still well below stock's | [CAMERA-PLAN](../device/cheetah/CAMERA-PLAN.md), [CAMERA-QUALITY-PLAN](CAMERA-QUALITY-PLAN.md) | | Suspend | WIP | s2idle works when asked for (`systemctl suspend`, `rtcwake`): `pm_test` dry runs, wakes on a volume key and on the RTC alarm, 20 of 20 unattended cycles (S3b, S4); UFS powers down in suspend by default (`spm_lvl` 5). Wi-Fi stays connected across sleep: 31 of 31 freezes with the D3 handshake (S5b-3, S5c, 2026-10-19), and the sleep hook keeps it loaded. The AoC and sensors work across sleep, and a running sensor stream doesn't wake the phone (S6, 2026-10-19). Screen off, with Wi-Fi up, it draws 434 mA awake and 312 mA in s2idle: about 16 h of standby on the 4986 mAh battery (S7, 2026-10-19), against 32-50 mA in stock's deep sleep. Auto-sleep is in the packages and off by default ([#64](https://github.com/derekross/omarchy-mobile/pull/64), omamobile-shell 0.2.29): with the `omamobile-sleep` toggle on, the phone sleeps 30 s after the screen goes off behind a secure lock and at once on Power, and Power wakes it to the PIN pad; 13 cycles in one boot with 0 failures (P0-P5, 2026-10-26). P5 stopped that day on a speaker trip that turned out not to come from sleep ([NOTES](../device/cheetah/NOTES.md#2026-10-27-the-muted-speakers-were-the-open-loop-coil-estimate-not-sleep-the-static-was-the-boost-converter-the-earpiece-is-the-top-speaker)); resumed on 2026-11-01, it passed with 11 suspends and 0 failures, the speakers fine across each sleep. After its power-key test Hyprland ran neither power-key bind until `hyprctl reload`; the on-screen keyboard's virtual keyboard was reaching the hardware-key binds, which now ignore it ([#312](https://github.com/derekross/omarchy-mobile/pull/312), omamobile-shell 0.2.75; re-tested on the phone 2026-11-01, [SUSPEND-PLAN](../device/cheetah/SUSPEND-PLAN.md) P5 test h). Still open: NetworkManager drops Wi-Fi for each sleep and reconnects about 5 s after the wake. The toggle stays off by default until a day of use (P6) and a power-off from Linux (P7) have run. Wi-Fi traffic and a USB plug can't wake it, a few RTC cycles wake early on a PMIC interrupt not yet identified, and the modem has never run across a suspend. Deep sleep (SYS_SLEEP), which stock's standby numbers need, is research and not started | [SUSPEND-PLAN](../device/cheetah/SUSPEND-PLAN.md) | -| Fingerprint | works (on by default for new installs) | Google's HAL in a chroot behind a bridge and Trusty's fingerprint TA on our kernel (F3-F9), fprintd with our libfprint driver: enrollment from the shell, and the lock screen unlocks with a finger alongside the PIN pad or password, with the keyboard usable over the lock (F16b). A verify stays open across system sleep, and an enrollment interrupted by sleep fails cleanly (libfprint 1.6, 2026-10-19). From omamobile-fingerprint 0.1.14 and omamobile-firstboot 0.1.4 it is on for new installs: the installer's warning names the secure-storage write and the typed codename is the consent, the runner makes its read-only copies itself and runs one storage proxy per boot (F19, 2026-11-02; the fresh-install checks T1-T3 are pending) | [FINGERPRINT-PLAN](../device/cheetah/FINGERPRINT-PLAN.md), [FINGERPRINT-RESEARCH](../device/cheetah/FINGERPRINT-RESEARCH.md) | +| Fingerprint | works (on by default) | Google's HAL in a chroot behind a bridge and Trusty's fingerprint TA on our kernel (F3-F9), fprintd with our libfprint driver: enrollment from the shell, and the lock screen unlocks with a finger alongside the PIN pad or password, with the keyboard usable over the lock (F16b). A verify stays open across system sleep, and an enrollment interrupted by sleep fails cleanly (libfprint 1.6, 2026-10-19). From omamobile-fingerprint 0.1.14 it starts by default after provisioning: the runner makes its read-only copies itself, refuses to start when the TDP copy changed, and runs one storage proxy per boot (F19, 2026-11-02; the fresh-install checks T1-T3 are pending) | [FINGERPRINT-PLAN](../device/cheetah/FINGERPRINT-PLAN.md), [FINGERPRINT-RESEARCH](../device/cheetah/FINGERPRINT-RESEARCH.md) | ## Wanted diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 5c66b9477..ca1af17be 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -197,7 +197,7 @@ tools/phone-ssh '(sleep 1; reboot-to omamobile) >/dev/null 2>&1 &' After the restart, Wi-Fi, Bluetooth, sound, haptics, the sensors and the cameras work. -**Fingerprint unlock works out of the box.** After this restart the phone offers "Add a fingerprint" (or find it later in Setup > Security > Fingerprint): touch the sensor under the bright circle until it's done, and the finger unlocks the phone alongside your PIN or password. As the installer's warning said, fingerprint's first start writes the phone's secure storage (Trusty's area in the UFS RPMB). That can't be undone, but it is the same kind of write Android makes at every factory reset. Before that first start the phone makes read-only copies of the data it needs from `persist` and the factory calibration (`mfg_data`); nothing is written to `persist`, `mfg_data`, the Titan M2 security chip or Android's slot A, and if those copies can't be made or later don't match, fingerprint stays off and the PIN unlocks. If fingerprint ever stops (after a crash, for example), restart the phone rather than restarting the service. +**Fingerprint unlock works after this restart.** The phone offers "Add a fingerprint" (or find it later in Setup > Security > Fingerprint): touch the sensor under the bright circle until it's done, and the finger unlocks the phone alongside your PIN or password. Its first start writes the phone's secure storage (Trusty's area in the UFS RPMB), the same kind of write Android makes at a factory reset; before that it makes read-only copies of the data it needs from `persist` and the factory calibration (`mfg_data`), which it never writes. If those copies can't be made or later don't match, fingerprint stays off and the PIN unlocks. If fingerprint stops, restart the phone rather than the service. ## Getting updates @@ -224,7 +224,7 @@ Stock Android is still on slot A. fastboot reboot ``` -3. Android starts into its recovery screen, because its data was erased. Choose "Factory data reset", and Android starts as a new phone. Fingerprints you enrolled on Omarchy Mobile stay behind: enroll your fingers again on Android (and again after you come back, since reinstalling erases them; never restore an old fingerprint backup). +3. Android starts into its recovery screen, because its data was erased. Choose "Factory data reset", and Android starts as a new phone. Fingers enrolled on Omarchy Mobile don't carry over: enroll them again on Android, and again after you come back (reinstalling erases them). To remove Omarchy Mobile completely, flash Google's factory image for your phone with Google's own tools (the [Android Flash Tool](https://flash.android.com) or the `flash-all.sh` script in the factory image). Don't lock the bootloader afterwards unless you're sure both slots hold Google's images; if in doubt, ask in an issue first. diff --git a/docs/release-notes/2026-11-DRAFT.md b/docs/release-notes/2026-11-DRAFT.md index b736c10a8..a1cebcd18 100644 --- a/docs/release-notes/2026-11-DRAFT.md +++ b/docs/release-notes/2026-11-DRAFT.md @@ -37,7 +37,7 @@ From [docs/DEVICES.md](../DEVICES.md) on the release day: | GNSS | Location through GeoClue, with a quick-settings tile | | NFC | Reads and writes tags; a tag with a link opens it | | Cameras | Main, ultrawide and front through libcamera; the telephoto at fixed focus | -| Fingerprint | On out of the box after provisioning: enrollment offered at setup, unlock on the lock screen | +| Fingerprint | Works after provisioning: enrollment offered at setup, unlock on the lock screen | | CPU | Frequency scaling and thermal zones | ### New in the last weeks @@ -50,7 +50,7 @@ From [docs/DEVICES.md](../DEVICES.md) on the release day: - **Updates** entry in the app drawer, with an update sheet that shows what's new and the phone's patches. - **Louder speakers** under the protection firmware, and an earpiece mode for calls. - **Files** opens folders with a single tap; the file chooser no longer stalls at login. -- **Fingerprint out of the box:** the installer's warning covers its secure-storage write, the phone makes its read-only copies of the calibration and `persist:/ss` itself, and setup offers "Add a fingerprint" after the PIN. +- **Fingerprint unlock after provisioning:** the phone makes its read-only copies of the calibration and `persist:/ss` itself, and setup offers "Add a fingerprint" after the PIN. ## Known issues @@ -59,7 +59,7 @@ From [docs/DEVICES.md](../DEVICES.md) on the release day: - **Cameras:** basic image quality (no Google ISP or tuning); the telephoto doesn't focus. - **Bluetooth:** headset calls (HFP) don't work yet. - **USB-C:** the phone is a USB device only (no host mode or role switch yet); after a replug, `omamobile-usb-rescue` reconnects it. -- **Fingerprint's first start writes the phone's secure storage** (Trusty's area in the RPMB, the same kind of write as an Android factory reset; nothing goes to `persist`, `mfg_data`, the Titan M2 or slot A). The installer's warning says so, and typing the codename acknowledges it. Going back to Android works as usual, with fingers enrolled again there. If fingerprint stops, restart the phone: it starts once per boot by design. +- **Fingerprint starts once per boot by design:** if it stops, restart the phone. Its first start writes the phone's secure storage (Trusty's area in the RPMB, the same kind of write as an Android factory reset); `persist` and `mfg_data` are only read. Fingers are enrolled again after a reinstall, and on Android if you go back. - **Google's firmware is not included** and never will be: after installing, the bundle's `tools/phone-provision` extracts it from your own factory image for your phone (Wi-Fi, Bluetooth, haptics, speakers, cameras). ## Phones already running a development build From b2ba7ee39c6adbd5740ce5dd0e4274b8eab72ae0 Mon Sep 17 00:00:00 2001 From: Derek Ross Date: Mon, 2 Nov 2026 19:02:56 -0500 Subject: [PATCH 13/15] omamobile-fingerprint 0.1.14: CI-safe namespace test, tighter markers, data-check refusals named From the round-2 review of #358: - test/all removed $nsroot/proc with a bare rmdir after the SKIP branch, so where user namespaces are off (CI) set -e ended the script: rm -rf instead. - The device and state overrides now need OMAMOBILE_FP_TEST=1 like the path overrides (the device comes from the board's compatible string; a forced "tegu" on a 7 Pro would skip the copies and hash checks). A read-only `paths` subcommand shows what is in use, and the test checks it instead of running preflight on the real paths. - The once-per-boot marker is created with noclobber (O_EXCL), so two racing starts can't both pass. - The inner start takes only a 32-hex token; post_upgrade's marker for an older runner's proxy carries none, so it only blocks. - Data-check refusals (the TDP copy, persist:/ss/0, ro=1, the mounts) write /run/omamobile-fp-ui/off-reason, since they recur at every boot; onboarding says so instead of "unavailable on this boot". - Tests now catch the three mutations that survived: the start-pending clear after "stage running", the namespace's EXIT trap, and post_upgrade's marker (run against a stub pgrep). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BeEcdVeSfyLCbijF8XQF1d --- .../lib/omamobile-fp-chroot | 49 +++++++++++++------ .../omamobile-fingerprint.install | 4 +- packages/omamobile-fingerprint/test/all | 11 ++++- packages/omamobile-fingerprint/test/preflight | 45 ++++++++++++++--- 4 files changed, 84 insertions(+), 25 deletions(-) diff --git a/packages/omamobile-fingerprint/lib/omamobile-fp-chroot b/packages/omamobile-fingerprint/lib/omamobile-fp-chroot index b798ffb29..b816ee5fc 100755 --- a/packages/omamobile-fingerprint/lib/omamobile-fp-chroot +++ b/packages/omamobile-fingerprint/lib/omamobile-fp-chroot @@ -5,6 +5,7 @@ # bring-up runbook in FINGERPRINT-PLAN.md). # # omamobile-fp-chroot check preconditions only; changes nothing +# omamobile-fp-chroot paths the device and paths in use; read-only # omamobile-fp-chroot preflight the safety checks a start runs before # storageproxyd (the read-only copies, # the TDP guard, once per boot). Not a @@ -57,8 +58,9 @@ # the AoC's sound and sensors with it), so that boot skips fingerprint # once and the one after tries again. # -# The overrides of the partitions' and markers' paths (OMAMOBILE_FP_RUN, -# _SYSBLOCK, _DEVDIR, _MOUNTS, _BOOT_ID) are honoured only with +# The overrides of the device, the state and the partitions' and markers' +# paths (OMAMOBILE_FP_DEVICE, _STATE, _RUN, _SYSBLOCK, _DEVDIR, _MOUNTS, +# _BOOT_ID, _UIDIR) are honoured only with # OMAMOBILE_FP_TEST=1, which the unit never sets (test/preflight). set -euo pipefail @@ -79,7 +81,9 @@ fp_device() { *) echo cheetah ;; esac } -DEVICE=${OMAMOBILE_FP_DEVICE:-$(fp_device)} +# From the board's compatible string; only test/preflight may override it +DEVICE=$(fp_device) +[[ ${OMAMOBILE_FP_TEST:-} == 1 ]] && DEVICE=${OMAMOBILE_FP_DEVICE:-$DEVICE} case $DEVICE in cheetah) TA=g7.app @@ -102,7 +106,8 @@ case $DEVICE in esac PANEL_NAME=${OMAMOBILE_FP_PANEL_NAME:-$PANEL_NAME} PROPS_DEVICE=${OMAMOBILE_FP_PROPS_DEVICE:-/usr/lib/omamobile-fp/props-$DEVICE.conf} -STATE=${OMAMOBILE_FP_STATE:-/var/lib/omamobile-fp} +STATE=/var/lib/omamobile-fp +[[ ${OMAMOBILE_FP_TEST:-} == 1 ]] && STATE=${OMAMOBILE_FP_STATE:-$STATE} RUN=/run/omamobile-fp # Where the partitions are found SYSBLOCK=/sys/class/block @@ -137,6 +142,7 @@ SOCKDIR=$RUN/sock # world-readable, unlike everything else here. In the chroot it is # /dev/socket/omamobile-fp-ui. UIDIR=/run/omamobile-fp-ui +[[ ${OMAMOBILE_FP_TEST:-} == 1 ]] && UIDIR=${OMAMOBILE_FP_UIDIR:-$UIDIR} # The shell keeps a file fresh in here while the on-screen keyboard is up # (its keys can cover the sensor); the bridge then ignores touches on the # sensor. Sticky and world-writable like /tmp: a user can only turn @@ -145,6 +151,13 @@ INHIBITDIR=$UIDIR/inhibit say() { printf 'omamobile-fp: %s\n' "$*" >&2; } die() { say "error: $*"; exit 1; } +# A refusal of the data checks: unlike a failed start it recurs at every +# boot until someone acts, so the desktop is told why (world-readable, like +# the bridge's state file; onboarding reads it). +refuse() { + install -d -m 0755 "$UIDIR" 2>/dev/null && echo data-check > "$UIDIR/off-reason" 2>/dev/null || true + die "$*" +} # Host tools, resolved now: the Android processes get an Android PATH, and # env(1) would look chroot up in that. @@ -266,9 +279,9 @@ ro_part() { local d d=$(part_dev "$1") || die "no $1 partition (PARTNAME=$1 in $SYSBLOCK/*/uevent)" [[ $(cat "$SYSBLOCK/$d/ro" 2>/dev/null) == 1 ]] || - die "$1 ($d) is not read-only: the storage guard must keep it ro=1. Nothing copied, nothing started" + refuse "$1 ($d) is not read-only: the storage guard must keep it ro=1. Nothing copied, nothing started" if awk -v d="$DEVDIR/$d" '$1 == d && $4 ~ /(^|,)rw(,|$)/ {f = 1} END {exit !f}' "$MOUNTS" 2>/dev/null; then - die "$1 ($d) is mounted read-write. Nothing copied, nothing started" + refuse "$1 ($d) is mounted read-write. Nothing copied, nothing started" fi printf '%s\n' "$d" } @@ -298,11 +311,11 @@ provision() { if [[ -e $STATE/persist-ss/0 ]]; then persist_dump /ss/0 "$tmp/0" "$p" || die "can't read persist:/ss/0 to check the existing TDP copy" cmp -s "$tmp/0" "$STATE/persist-ss/0" || - die "$STATE/persist-ss/0 differs from persist:/ss/0: Linux's TDP copy and stock's no longer agree. Not starting: ask (FINGERPRINT-PLAN F19)" + refuse "$STATE/persist-ss/0 differs from persist:/ss/0: Linux's TDP copy and stock's no longer agree. Not starting: ask (FINGERPRINT-PLAN F19)" say "the existing TDP copy matches persist:/ss/0: recording it" else persist_dump /ss/0 "$tmp/0" "$p" || - die "persist has no /ss/0 (or it can't be read): without a TDP copy storageproxyd won't start" + refuse "persist has no /ss/0 (or it can't be read): without a TDP copy storageproxyd won't start" persist_dump /ss/nsp "$tmp/nsp" "$p" || say "persist has no /ss/nsp: Trusty starts an empty one (it has no rollback check)" mv "$tmp/0" "$STATE/persist-ss/0" @@ -345,16 +358,16 @@ tdp_guard() { # the 9a: TDP is tdp.img, the F3 copy of trusty_persist (before the # first mapped run, that copy as persist-ss/0) [[ -f $STATE/tdp.img || ( -f $STATE/persist-ss/0 && ! -L $STATE/persist-ss/0 && -s $STATE/persist-ss/0 ) ]] || - die "no TDP copy ($STATE/tdp.img): storageproxyd won't start without it (device/tegu/FINGERPRINT-PLAN.md F4b)" + refuse "no TDP copy ($STATE/tdp.img): storageproxyd won't start without it (device/tegu/FINGERPRINT-PLAN.md F4b)" return 0 fi [[ -s $STATE/persist-ss/0 ]] || - die "no TDP copy ($STATE/persist-ss/0, recorded in $PROVENANCE): storageproxyd won't start without it. Don't recreate it by hand: ask (FINGERPRINT-PLAN F19)" + refuse "no TDP copy ($STATE/persist-ss/0, recorded in $PROVENANCE): storageproxyd won't start without it. Don't recreate it by hand: ask (FINGERPRINT-PLAN F19)" want=$(recorded persist-ss/0) [[ -n $want ]] || die "$PROVENANCE has no persist-ss/0 line" got=$(sha "$STATE/persist-ss/0") [[ $got == "$want" ]] || - die "the TDP copy changed (sha256 ${got:0:16}, recorded ${want:0:16}): Linux wrote Trusty's persistent store, so stock's persist:/ss/0 no longer matches the RPMB. Refusing to start: report it (FINGERPRINT-PLAN F19)" + refuse "the TDP copy changed (sha256 ${got:0:16}, recorded ${want:0:16}): Linux wrote Trusty's persistent store, so stock's persist:/ss/0 no longer matches the RPMB. Refusing to start: report it (FINGERPRINT-PLAN F19)" p=$(ro_part persist) install -d -m 0755 "$RUN" tmp=$RUN/persist-ss0.check @@ -362,7 +375,7 @@ tdp_guard() { got=$(sha "$tmp") rm -f "$tmp" [[ $got == "$want" ]] || - die "persist:/ss/0 changed since the copy was made (sha256 ${got:0:16}, recorded ${want:0:16}; did stock Android run?): the copy no longer matches the RPMB. Refusing to start: ask (FINGERPRINT-PLAN F19)" + refuse "persist:/ss/0 changed since the copy was made (sha256 ${got:0:16}, recorded ${want:0:16}; did stock Android run?): the copy no longer matches the RPMB. Refusing to start: ask (FINGERPRINT-PLAN F19)" want=$(recorded mfg_data.img) if [[ -n $want && -f $STATE/mfg_data.img && $(sha "$STATE/mfg_data.img") != "$want" ]]; then say "warning: $STATE/mfg_data.img differs from its recorded copy (the partition itself is never written)" @@ -387,9 +400,13 @@ preflight() { fi ((MAP_STORES)) || provision tdp_guard + rm -f "$UIDIR/off-reason" 2>/dev/null || true install -d -m 0755 "$RUN" TOKEN=$(head -c 16 /dev/urandom | od -An -tx1 | tr -d ' \n') - (umask 077; echo "$(date -Is 2>/dev/null || date) pid $$ token $TOKEN" > "$MARKER") + # noclobber opens with O_EXCL: of two starts racing past the check above, + # only one gets the marker + (set -o noclobber; umask 077; echo "$(date -Is 2>/dev/null || date) pid $$ token $TOKEN" > "$MARKER") 2>/dev/null || + die "secure storage already ran this boot (another start got there first). Reboot to start fingerprint again" install -d -m 0700 "$STATE" echo "$boot $(date -Is 2>/dev/null || date)" > "$PENDING" } @@ -596,7 +613,7 @@ start() { if [[ -n ${OMAMOBILE_FP_IN_NS:-} ]]; then # Only after this boot's preflight: its marker carries the token it # handed down, so OMAMOBILE_FP_IN_NS=1 alone can't skip the checks. - [[ -n ${OMAMOBILE_FP_TOKEN:-} && -f $MARKER && $(sed -n 's/.* token //p' "$MARKER") == "$OMAMOBILE_FP_TOKEN" ]] || + [[ ${OMAMOBILE_FP_TOKEN:-} =~ ^[0-9a-f]{32}$ && -f $MARKER && $(sed -n 's/.* token //p' "$MARKER") == "$OMAMOBILE_FP_TOKEN" ]] || die "the inner start runs only after this boot's preflight (omamobile-fp-chroot start)" fi # Modules the stack needs, blacklisted from autoload (omamobile-device- @@ -726,9 +743,11 @@ run() { case ${1:-} in check) check ;; preflight) preflight ;; + paths) printf '%s\n' "device=$DEVICE" "state=$STATE" "run=$RUN" "sysblock=$SYSBLOCK" "devdir=$DEVDIR" \ + "mounts=$MOUNTS" "boot_id=$BOOT_ID_FILE" "uidir=$UIDIR" ;; start) start "${2:-bridge}" ;; ns) shift; ns "$@" ;; run) shift; run "$@" ;; - *) echo "usage: omamobile-fp-chroot check | preflight | start [storage|apploader|keys|hal|bridge] | ns CMD... | run CMD..." >&2 + *) echo "usage: omamobile-fp-chroot check | paths | preflight | start [storage|apploader|keys|hal|bridge] | ns CMD... | run CMD..." >&2 exit 2 ;; esac diff --git a/packages/omamobile-fingerprint/omamobile-fingerprint.install b/packages/omamobile-fingerprint/omamobile-fingerprint.install index 51a0f9f35..b13068d8b 100644 --- a/packages/omamobile-fingerprint/omamobile-fingerprint.install +++ b/packages/omamobile-fingerprint/omamobile-fingerprint.install @@ -10,9 +10,9 @@ post_upgrade() { # so the new runner refuses a second proxy until the reboot. if pgrep -x storageproxyd >/dev/null 2>&1 && [[ ! -e /run/omamobile-fp/storageproxyd-started ]]; then mkdir -p /run/omamobile-fp - (umask 077; echo "$(date -Is) started before the upgrade token none" > /run/omamobile-fp/storageproxyd-started) + (umask 077; echo "$(date -Is) started before the upgrade (no token)" > /run/omamobile-fp/storageproxyd-started) fi - echo "omamobile-fingerprint: fingerprint starts again at the next boot (one storage proxy per boot)" + echo "omamobile-fingerprint: reboot soon: fingerprint starts again at the next boot (one storage proxy per boot)" } pre_remove() { systemctl disable --now omamobile-fp.service 2>/dev/null || true diff --git a/packages/omamobile-fingerprint/test/all b/packages/omamobile-fingerprint/test/all index 0b620cc73..fd482234b 100755 --- a/packages/omamobile-fingerprint/test/all +++ b/packages/omamobile-fingerprint/test/all @@ -78,6 +78,15 @@ order=$(sed -n '/^stop() {/,/^}/p' lib/omamobile-fp-chroot | sed -n 's/^ *stop_c [[ $order == "bridge fingerprint|gatekeeper keymint|storageproxyd|" ]] || fail "stop order: $order" grep -c 'ln -sfn ../omamobile-fp.service "$d/usr/lib/systemd/system/multi-user.target.wants/omamobile-fp.service"' install >/dev/null || fail "the package enables omamobile-fp itself (so only this runner is ever enabled by default)" +# A good start clears its pending marker (else every other boot would skip), +# a die in the namespace still stops in order, and the marker is taken +# atomically +st=$(sed -n '/^start() {/,/^}/p' lib/omamobile-fp-chroot) +grep -A1 '^ say "stage \$stage running"$' <<<"$st" | grep -qx ' rm -f "\$PENDING"' || + fail "start clears start-pending right after the stack runs" +grep -qx " trap 'stop \$?' EXIT" <<<"$st" || fail "the namespace's EXIT trap keeps the stop order on a die" +grep -c 'set -o noclobber; umask 077; echo .* > "\$MARKER"' lib/omamobile-fp-chroot >/dev/null || + fail "the once-per-boot marker is created with O_EXCL (noclobber)" echo "ok - one start per boot, no restart loop, the storage proxy stopped last" # alive() and stop_children() in a real PID namespace (the runner's PIDS[] @@ -119,7 +128,7 @@ if unshare --user --map-root-user --mount --propagation private --pid --fork \ else echo "ok - alive() in a PID namespace # SKIP no unprivileged user namespaces here" fi -rmdir "$nsroot/proc" 2>/dev/null; rmdir "$nsroot" 2>/dev/null || true +rm -rf "$nsroot" if [[ ! -f prebuilt/omamobile-fp-shim.so ]]; then echo "ok - the rest # SKIP no bionic prebuilts in this checkout (built on the computer)" diff --git a/packages/omamobile-fingerprint/test/preflight b/packages/omamobile-fingerprint/test/preflight index cbbbbe6e9..9d3b0b4b4 100755 --- a/packages/omamobile-fingerprint/test/preflight +++ b/packages/omamobile-fingerprint/test/preflight @@ -58,7 +58,7 @@ EOF pf() { PATH=$t/p/bin:$PATH OMAMOBILE_FP_TEST=${TESTMODE-1} OMAMOBILE_FP_BOOT_ID=$t/p/boot_id \ OMAMOBILE_FP_DEVICE=${DEV:-cheetah} OMAMOBILE_FP_STATE=$t/p/state \ - OMAMOBILE_FP_RUN=$t/p/run/omamobile-fp \ + OMAMOBILE_FP_RUN=$t/p/run/omamobile-fp OMAMOBILE_FP_UIDIR=$t/p/ui \ OMAMOBILE_FP_SYSBLOCK=$t/p/sys OMAMOBILE_FP_DEVDIR=$t/p/dev OMAMOBILE_FP_MOUNTS=$t/p/mounts \ "$RUNNER" preflight > "$t/out" 2>&1 } @@ -85,6 +85,7 @@ grep -v -c 'debugfs -R dump -p ' "$t/p/debugfs.log" >/dev/null && fail "debugfs grep -c ' token [0-9a-f]\{32\}$' "$marker" >/dev/null || fail "the marker carries the token for the inner start" [[ $(stat -c %a "$marker") == 600 ]] || fail "the marker (and its token) is root's only" [[ $(cut -d' ' -f1 "$S/start-pending") == boot-1 ]] || fail "the start is pending until it runs" +[[ ! -e $t/p/ui/off-reason ]] || fail "a passing preflight leaves no off-reason" pass "a first start: mfg_data and persist:/ss copied read-only and their hashes recorded" # A second start in the same boot @@ -112,6 +113,7 @@ phone; pf || fail "setup" newboot; echo x >> "$S/persist-ss/0" pf && fail "a changed TDP copy is refused" grep -c 'TDP copy changed' "$t/out" >/dev/null || { cat "$t/out"; fail "says the TDP copy changed"; } +[[ $(cat "$t/p/ui/off-reason" 2>/dev/null) == data-check ]] || fail "a data-check refusal tells the desktop why (off-reason)" pass "the TDP copy changed since the record: refused" # persist:/ss/0 changed under the copy (a stock boot) @@ -161,15 +163,24 @@ grep -c 'never got running' "$t/out" >/dev/null || { cat "$t/out"; fail "says wh pf || { cat "$t/out"; fail "the boot after it tries again (the pending marker went)"; } pass "a start that never got running: the next boot skips once, then it starts again" -# The path overrides only count in the test mode -phone -TESTMODE=0 pf && fail "without OMAMOBILE_FP_TEST=1 the fake tree is ignored" -[[ ! -e $marker && ! -e $S/provenance ]] || fail "the overrides redirected nothing outside the test mode" -pass "the partitions' and markers' path overrides need OMAMOBILE_FP_TEST=1" +# The overrides only count in the test mode (read-only: the paths subcommand) +ov() { env OMAMOBILE_FP_TEST="$1" OMAMOBILE_FP_DEVICE=tegu OMAMOBILE_FP_STATE=/x/state OMAMOBILE_FP_RUN=/x/run \ + OMAMOBILE_FP_SYSBLOCK=/x/sys OMAMOBILE_FP_DEVDIR=/x/dev OMAMOBILE_FP_MOUNTS=/x/mounts OMAMOBILE_FP_BOOT_ID=/x/boot \ + OMAMOBILE_FP_UIDIR=/x/ui "$RUNNER" paths; } +real=$(ov 0) fake=$(ov 1) +for l in state=/var/lib/omamobile-fp run=/run/omamobile-fp sysblock=/sys/class/block devdir=/dev mounts=/proc/mounts \ + boot_id=/proc/sys/kernel/random/boot_id uidir=/run/omamobile-fp-ui; do + grep -qx "$l" <<<"$real" || fail "without OMAMOBILE_FP_TEST=1: $l ($real)" +done +grep -qx 'device=tegu' <<<"$real" && fail "without OMAMOBILE_FP_TEST=1 the device comes from the board, not OMAMOBILE_FP_DEVICE" +for l in device=tegu state=/x/state run=/x/run sysblock=/x/sys devdir=/x/dev mounts=/x/mounts boot_id=/x/boot uidir=/x/ui; do + grep -qx "$l" <<<"$fake" || fail "with OMAMOBILE_FP_TEST=1: $l" +done +pass "the device, state and path overrides need OMAMOBILE_FP_TEST=1" # The inner start needs this boot's preflight token phone; pf || fail "setup" -for tok in "" wrong none; do +for tok in "" wrong none 0123456789abcdef0123456789abcdef; do if PATH=$t/p/bin:$PATH OMAMOBILE_FP_TEST=1 OMAMOBILE_FP_RUN=$t/p/run/omamobile-fp OMAMOBILE_FP_STATE=$S \ OMAMOBILE_FP_IN_NS=1 OMAMOBILE_FP_TOKEN=$tok "$RUNNER" start storage > "$t/out" 2>&1; then fail "the inner start with token '$tok' is refused" @@ -185,4 +196,24 @@ mkdir -p "$S"; head -c 512 /dev/urandom > "$S/tdp.img" DEV=tegu pf || { cat "$t/out"; fail "tegu with tdp.img passes"; } pass "the 9a: refused without its TDP image" +# post_upgrade: an older runner's proxy still running sets a marker that +# blocks a second proxy and that no token can pass +phone +mkdir -p "$t/p/stub"; printf '#!/bin/bash\nexit 0\n' > "$t/p/stub/pgrep"; printf '#!/bin/bash\nexit 0\n' > "$t/p/stub/systemctl" +chmod +x "$t/p/stub/pgrep" "$t/p/stub/systemctl" +sed "s|/run/omamobile-fp|$t/p/run/omamobile-fp|g" omamobile-fingerprint.install > "$t/scriptlet" +( PATH=$t/p/stub:$PATH; source "$t/scriptlet"; post_upgrade ) > /dev/null +[[ -e $marker ]] || fail "post_upgrade marks a proxy started by an older runner" +pf && fail "after that marker, a start in the upgrade boot is refused" +for tok in "" none "$(sed -n 's/.* token //p' "$marker")"; do + if PATH=$t/p/bin:$PATH OMAMOBILE_FP_TEST=1 OMAMOBILE_FP_RUN=$t/p/run/omamobile-fp OMAMOBILE_FP_STATE=$S \ + OMAMOBILE_FP_IN_NS=1 OMAMOBILE_FP_TOKEN=$tok "$RUNNER" start storage > "$t/out" 2>&1; then + fail "the inner start passes post_upgrade's marker with token '$tok'" + fi +done +rm -f "$marker"; printf '#!/bin/bash\nexit 1\n' > "$t/p/stub/pgrep" +( PATH=$t/p/stub:$PATH; source "$t/scriptlet"; post_upgrade ) > /dev/null +[[ ! -e $marker ]] || fail "post_upgrade sets no marker when no proxy runs" +pass "post_upgrade: an older runner's running proxy blocks a second one, and its marker passes no token" + echo "omamobile-fingerprint preflight: ok" From a606548ef1a6bb121084cb8490a601475aa7e859 Mon Sep 17 00:00:00 2001 From: Derek Ross Date: Mon, 2 Nov 2026 19:02:56 -0500 Subject: [PATCH 14/15] omamobile-shell 0.2.89: onboarding names a data-check refusal A refusal of the runner's data checks (the TDP copy or persist:/ss/0 no longer matching) recurs at every boot, so onboarding says fingerprint is off until it is looked at, rather than "unavailable on this boot". It reads the runner's /run/omamobile-fp-ui/off-reason. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BeEcdVeSfyLCbijF8XQF1d --- packages/omamobile-shell/bin/omamobile-onboarding | 6 +++++- packages/omamobile-shell/test/onboarding-fingerprint.sh | 7 +++++-- 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/packages/omamobile-shell/bin/omamobile-onboarding b/packages/omamobile-shell/bin/omamobile-onboarding index 18d4511f2..06a7a4caa 100644 --- a/packages/omamobile-shell/bin/omamobile-onboarding +++ b/packages/omamobile-shell/bin/omamobile-onboarding @@ -21,6 +21,8 @@ set -u omarchy_path=${OMARCHY_PATH:-/usr/share/omarchy} fp_runner=${OMAMOBILE_FP_RUNNER:-/usr/lib/omamobile-fp/omamobile-fp-chroot} fp_image=${OMAMOBILE_FP_IMAGE:-/usr/lib/omamobile-fp/root} +# the runner says here why it refused (off-reason: data-check recurs every boot) +fp_uidir=${OMAMOBILE_FP_UIDIR:-/run/omamobile-fp-ui} fp_offered=${XDG_STATE_HOME:-$HOME/.local/state}/omamobile/fingerprint-offered has_identity() { @@ -76,7 +78,9 @@ offer_fingerprint() { n=$(fp_count) if [[ -z $n ]]; then echo - if systemctl is-failed --quiet omamobile-fp.service 2>/dev/null; then + if [[ $(cat "$fp_uidir/off-reason" 2>/dev/null) == data-check ]]; then + echo "Fingerprint unlock is off: its check of stock Android's data failed, and it stays off until that is looked at (journalctl -u omamobile-fp; FINGERPRINT-PLAN F19). Your PIN or password unlocks the phone." + elif systemctl is-failed --quiet omamobile-fp.service 2>/dev/null; then echo "Fingerprint unlock is unavailable on this boot (see journalctl -u omamobile-fp). Your PIN or password unlocks the phone." elif [[ ! -d $fp_image ]]; then echo "Fingerprint unlock will be ready once your phone's firmware is added and it restarts. The phone offers it then." diff --git a/packages/omamobile-shell/test/onboarding-fingerprint.sh b/packages/omamobile-shell/test/onboarding-fingerprint.sh index 3ff6784be..2a0883eb3 100644 --- a/packages/omamobile-shell/test/onboarding-fingerprint.sh +++ b/packages/omamobile-shell/test/onboarding-fingerprint.sh @@ -25,10 +25,10 @@ fake omarchy-notification-send 'echo "notify $*" >>"$T/log"' fake systemctl '[[ $* == "is-failed --quiet omamobile-fp.service" && -e $T/failed ]]' fake timeout 'shift; "$@"' ob() { - env -u XDG_STATE_HOME T="$t" HOME="$t/home" USER=alice OMARCHY_PATH="$t/none" OMAMOBILE_FP_RUNNER="$t/runner" OMAMOBILE_FP_IMAGE="$t/image" \ + env -u XDG_STATE_HOME T="$t" HOME="$t/home" USER=alice OMARCHY_PATH="$t/none" OMAMOBILE_FP_RUNNER="$t/runner" OMAMOBILE_FP_IMAGE="$t/image" OMAMOBILE_FP_UIDIR="$t/ui" \ PATH="$F:/usr/bin:/bin" bash bin/omamobile-onboarding "$@" >"$t/out" 2>&1 } -reset() { rm -rf "$t/pin" "$t/yes" "$t/listing" "$t/failed" "$t/image" "$t/log"; rm -rf "$t/home/.local"; : >"$t/log"; } +reset() { rm -rf "$t/pin" "$t/yes" "$t/listing" "$t/failed" "$t/image" "$t/ui" "$t/log"; rm -rf "$t/home/.local"; : >"$t/log"; } ready() { printf '{"event": "fingers", "fingers": [%s], "stages": 12, "device": "Omarchy Mobile UDFPS"}\n' "${1:-}" >"$t/listing"; } # Setup: the PIN is set, then the fingerprint is offered and taken @@ -52,6 +52,9 @@ grep -c 'ready once your phone' "$t/out" >/dev/null || fail "not provisioned yet reset; mkdir "$t/image"; touch "$t/failed" ob --inner; grep -c 'unavailable on this boot' "$t/out" >/dev/null || fail "a refused or failed unit: setup says unavailable, not 'after the firmware'" grep -c 'ready once your phone' "$t/out" >/dev/null && fail "a failed unit isn't blamed on missing firmware" +reset; mkdir "$t/image" "$t/ui"; touch "$t/failed"; echo data-check > "$t/ui/off-reason" +ob --inner; grep -c "check of stock Android's data failed" "$t/out" >/dev/null || fail "a data-check refusal says so (it recurs every boot)" +grep -c 'unavailable on this boot' "$t/out" >/dev/null && fail "a data-check refusal isn't shown as a one-boot failure" reset; mkdir "$t/image" ob --inner; grep -c 'still starting' "$t/out" >/dev/null || fail "provisioned but not up yet: offered at the next login" reset From da9920521d57fcd84c178232061ed03a79d335ae Mon Sep 17 00:00:00 2001 From: Derek Ross Date: Mon, 2 Nov 2026 19:02:56 -0500 Subject: [PATCH 15/15] AGENTS, INSTALL, FINGERPRINT plans: mask to turn fingerprint off, guards per phone, plain wording - The vendor wants link survives `systemctl disable`, so the rollbacks (cheetah FINGERPRINT-PLAN F10, FINGERPRINT-RESEARCH, tegu F10) and AGENTS say `systemctl mask omamobile-fp`, and INSTALL tells owners how to keep it off before the provisioning restart. - AGENTS names the guards per phone (the 7 Pro's copies, hashes and persist:/ss/0 check; the 9a's tdp.img check; once per boot on both) and says storageproxyd "can write" TD superblocks at every start. - INSTALL and the release notes say fingerprint unlock starts automatically after provisioning; on Android, its setup asks for fingerprints as usual. DEVICES marks the automatic path as being tested. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BeEcdVeSfyLCbijF8XQF1d --- AGENTS.md | 2 +- device/cheetah/FINGERPRINT-PLAN.md | 2 +- device/cheetah/FINGERPRINT-RESEARCH.md | 2 +- device/tegu/FINGERPRINT-PLAN.md | 2 +- docs/DEVICES.md | 2 +- docs/INSTALL.md | 4 ++-- docs/release-notes/2026-11-DRAFT.md | 4 ++-- 7 files changed, 9 insertions(+), 9 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 74bf8d8f6..8daa92c54 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -156,7 +156,7 @@ Each entry gives the gotcha, then the reason or the fix. Details are in the link - **ACPM reads its channel table from APM SRAM, and some channels are unusable** (a type-2 buffer channel with queues in DRAM): skip them rather than failing the probe. DVFS is channel 0, PMIC 2, thermal 9. Upstream supports polling only. [ACPM-PLAN](device/cheetah/ACPM-PLAN.md) - **The regulator core turns off unused rails that have constraints about 30 s after late init:** load PMIC regulator modules after that, or make sure the rails are claimed. Since #227 the shared kernel builds `sec_acpm` in (the Pixel 9a's USB PHY needs its S2MPG14 rails at boot), so on the 7 Pro the S2MPG13 rails in the DT register before that cleanup and a `blacklist sec_acpm` does nothing; LDO9S-11S are GNSS-only, and LDO15S (`vdd_udfps`, the fingerprint sensor) and LDO12S (`vddio_cam`, camera I/O) are claimed by their drivers when those load, so the cleanup only turns off rails with no consumer yet. The fingerprint and camera starts' `modprobe sec_acpm` is a no-op there too. [GNSS-PLAN](device/cheetah/GNSS-PLAN.md) - **The AoC starts only through Trusty** (`com.android.trusty.gsa.hwmgr.aoc`). The GSA mailbox `START` leaves the A32 held. So Trusty is a dependency of audio and sensors, not just of fingerprint, and it runs at every boot on the integration kernel. -- **Fingerprint: `omamobile-fp` starts by default** (omamobile-fingerprint 0.1.14 enables it; it is inert until `tools/phone-provision` has pushed Google's files). Its storageproxyd writes Trusty's TD superblocks to the RPMB at every boot, the first time like an Android factory reset. What keeps stock's persistent data safe is the runner's guards: read-only copies of `mfg_data` and `persist:/ss` (debugfs, `persist` never mounted), a refusal to start when the TDP copy is missing or differs from its recorded hash or `persist:/ss/0` changed, and one storage proxy per boot. Never write `persist` or `mfg_data`, never weaken those guards, and never stop and start `omamobile-fp` (or any storageproxyd) in the same boot: Trusty keeps its storage state until a reboot, and a restart between TD's clear and its first commit crashed Trusty's storage app (F19), so reboot instead (the runner refuses a second start). Never restore an old TD (`phone-provision --restore-td` only if no storageproxyd ran since the backup). Starting the stack by hand where it isn't running (stage starts, runbooks) is still the human's call. [FINGERPRINT-PLAN](device/cheetah/FINGERPRINT-PLAN.md) F19 +- **Fingerprint: `omamobile-fp` starts by default** (omamobile-fingerprint 0.1.14 enables it with a vendor wants link; it is inert until `tools/phone-provision` has pushed Google's files). Its storageproxyd can write Trusty's TD superblocks to the RPMB at every start, the first time like an Android factory reset. What keeps stock's persistent data safe is the runner's guards. On the 7 Pro: read-only copies of `mfg_data` and `persist:/ss` (debugfs, `persist` never mounted), their recorded hashes, and a refusal to start when the TDP copy is missing or differs from its record or `persist:/ss/0` changed. On the 9a: only that the TDP image (`tdp.img`) exists. On both: one storage proxy per boot. Never write `persist` or `mfg_data`, never weaken those guards, and never stop and start `omamobile-fp` (or any storageproxyd) in the same boot: Trusty keeps its storage state until a reboot, and a restart between TD's clear and its first commit crashed Trusty's storage app (F19), so reboot instead (the runner refuses a second start). To keep it off, `systemctl mask omamobile-fp` (`disable` doesn't, because of the vendor link). Never restore an old TD (`phone-provision --restore-td` only if no storageproxyd ran since the backup). Starting the stack by hand where it isn't running (stage starts, runbooks) is still the human's call. [FINGERPRINT-PLAN](device/cheetah/FINGERPRINT-PLAN.md) F19 - **Set the Bluetooth address only after powering the controller on:** set on a never-powered controller, the kernel withdrew the index for good. - **spi-s3c64xx with automatic chip select dropped bits between transfers before linux-omarchy-mobile#150 (merged 2026-10-31):** its FIFO flush cleared the packet count before turning the channels off, so the controller clocked a few bits with the slave still selected. A slave that restarts per chip-select cycle (touch) doesn't notice; one that streams across cycles (the 9a's GNSS core, CHPP) loses 2-6 bits per transfer, and every read lands at a different bit offset. [tegu MODEM-PLAN](device/tegu/MODEM-PLAN.md) "G3, GNSS gets a fix" - **A node without pinctrl runs on the bootloader's pins, and a pin change tested next to another fix proves nothing on its own.** The 9a's GNSS SPI has no pin group and runs at the bootloader's drive 0; raising the drive looked like it cleaned the data, but it was tested together with the SPI flush fix, and with the flush fix alone at drive 0 the data was just as clean (linux-omarchy-mobile#151 closed). Read the bank's CON/PUD/DRV in `/sys/kernel/debug/pinctrl//pins` (one controller at a time, as the gs101 note above says) before changing anything, then change one thing per boot, and check whose pins they are in the vendor tree before claiming them (gpp22 is the eSE's). [tegu MODEM-PLAN](device/tegu/MODEM-PLAN.md) "G3, GNSS gets a fix" diff --git a/device/cheetah/FINGERPRINT-PLAN.md b/device/cheetah/FINGERPRINT-PLAN.md index b6de14d58..4c946241a 100644 --- a/device/cheetah/FINGERPRINT-PLAN.md +++ b/device/cheetah/FINGERPRINT-PLAN.md @@ -565,7 +565,7 @@ tools/phone-ssh 'systemctl enable omamobile-fp.service' reader and installs `libfprint-git`.) Lock, wake the screen, touch the circle: unlocks. The PIN still unlocks; with the service stopped the lock falls back to the PIN. Rollback: `rm /etc/pam.d/omarchy-lock-fingerprint`, -`systemctl disable --now omamobile-fp`. +`systemctl mask --now omamobile-fp` (from 0.1.14 the package's vendor wants link survives `disable`). ### F11: later diff --git a/device/cheetah/FINGERPRINT-RESEARCH.md b/device/cheetah/FINGERPRINT-RESEARCH.md index 40bacb867..025bf248d 100644 --- a/device/cheetah/FINGERPRINT-RESEARCH.md +++ b/device/cheetah/FINGERPRINT-RESEARCH.md @@ -631,7 +631,7 @@ Rollback: `fprintd-delete $USER`. Enable `omamobile-fp.service` and fprintd. Lock, wake the screen, touch the target: unlocks. The password still unlocks; with the service stopped the lock falls back to the password. -Rollback: `systemctl disable --now omamobile-fp`. +Rollback: `systemctl mask --now omamobile-fp` (from 0.1.14 the package's vendor wants link survives `disable`). --- diff --git a/device/tegu/FINGERPRINT-PLAN.md b/device/tegu/FINGERPRINT-PLAN.md index 28e3b777c..7a04264ac 100644 --- a/device/tegu/FINGERPRINT-PLAN.md +++ b/device/tegu/FINGERPRINT-PLAN.md @@ -392,7 +392,7 @@ match and a non-match, then libfprint and fprintd, then the PAM file and `omamobile-fp.service` enabled. Tune the LHBM settle time for tg4c's two-frame delay at 120 Hz. **Stop** on auth-token refusals, lockouts or TOO_DARK on every capture (then the overdrive brightness sets, section 3). -Rollback: delete the enrolled id, remove the PAM file, disable the service. +Rollback: delete the enrolled id, remove the PAM file, `systemctl mask --now omamobile-fp` (from 0.1.14 the package's vendor wants link survives `disable`). ### F11: shell and polish diff --git a/docs/DEVICES.md b/docs/DEVICES.md index 551d59874..6a4c6e026 100644 --- a/docs/DEVICES.md +++ b/docs/DEVICES.md @@ -56,7 +56,7 @@ The status of each device, as verified on real hardware. Rows in the matrix have | NFC | works | ST54J over I2C through st-nci with our plain-NCI link, loaded at boot; neard (patched for empty Type 4 tags) reads and writes tags, and tapping a tag with a web link opens it (`omamobile-nfc-open`): writing a tag and opening its link tested on the phone (N3). Card emulation and the secure element are not used | [RADIOS-CAMERA-PLAN](../device/cheetah/RADIOS-CAMERA-PLAN.md) §3 | | Cameras | works (telephoto fixed-focus) | Ultrawide (Sony IMX386, D-PHY link 2): works end to end through our CSIS/WDMA driver and libcamera's software ISP (CAM5), basic quality (no Google ISP or tuning); a libcamera build with autofocus and low-light patches is installed, not yet evaluated (CAM5.3). Front (Samsung S5K3J1, D-PHY link 0): real images, raw and through libcamera (`cam -c1`, 30 fps, no WDMA errors; F.5-F.7, 2026-10-13). Main (Samsung S5KGN1, C-PHY link 1): 2016x1136 at 30 fps through libcamera with no WDMA errors. Telephoto (S5KGM5, C-PHY): 26 fps through libcamera, colour bars correct; its lens (SEM1215) isn't driven yet, so it stays at its resting focus: distant subjects are sharp (outdoors, 2026-10-26), close ones soft, and tap to focus does nothing. The CSIS write DMA (not the link) loses lines that arrive faster than about 400 MB/s within a line, so the sensors lengthen their lines to stay under `samsung,max-line-throughput` (360 in cheetah's DT for the main, telephoto and front cameras; the front's full 3840x2736 mode runs at 26 fps). The ultrawide (imx386) follows the same rule, so its full 4032x3016 mode streams (23 fps; one run in several still showed WDMA errors), and with 384 MiB of CMA `cam` without options runs every camera at full size (main 12 MP at 9.4 fps). The telephoto's lens (SEM1215) answers on a 950 kHz bus but holds the bus when driven longer, so the telephoto runs at fixed focus. Sensor and DC-PHY settings come from the user's own camera software (`tools/extract-camera-data`), never shipped. Since omamobile-device-cheetah 0.1.30 the camera modules load after boot (`omamobile-camera.timer`), the DMA-BUF heaps are open to the session (libcamera's software ISP), WirePlumber names them Main, Ultrawide, Telephoto and Front camera (0.1.31). The default camera app is omacam ("Camera", omamobile-apps 0.2.0; [CAMERA-APP-PLAN](CAMERA-APP-PLAN.md)): libcamera directly, zoom across the three back lenses, full-resolution photos. GNOME Snapshot is optional, named "Snapshot", for video until omacam records it; browsers and video calls use the cameras through PipeWire (`pipewire-libcamera`). Picture quality: libcamera 0.7.2-4.21 adds chroma noise reduction and defective pixel correction, and omacam 0.3.3 has Night mode and an HDR chip, bursts of raw frames aligned, merged and finished on the phone (Night: 12 frames in about 4.6 s, Q5.3 on 2026-10-21); single shots are still well below stock's | [CAMERA-PLAN](../device/cheetah/CAMERA-PLAN.md), [CAMERA-QUALITY-PLAN](CAMERA-QUALITY-PLAN.md) | | Suspend | WIP | s2idle works when asked for (`systemctl suspend`, `rtcwake`): `pm_test` dry runs, wakes on a volume key and on the RTC alarm, 20 of 20 unattended cycles (S3b, S4); UFS powers down in suspend by default (`spm_lvl` 5). Wi-Fi stays connected across sleep: 31 of 31 freezes with the D3 handshake (S5b-3, S5c, 2026-10-19), and the sleep hook keeps it loaded. The AoC and sensors work across sleep, and a running sensor stream doesn't wake the phone (S6, 2026-10-19). Screen off, with Wi-Fi up, it draws 434 mA awake and 312 mA in s2idle: about 16 h of standby on the 4986 mAh battery (S7, 2026-10-19), against 32-50 mA in stock's deep sleep. Auto-sleep is in the packages and off by default ([#64](https://github.com/derekross/omarchy-mobile/pull/64), omamobile-shell 0.2.29): with the `omamobile-sleep` toggle on, the phone sleeps 30 s after the screen goes off behind a secure lock and at once on Power, and Power wakes it to the PIN pad; 13 cycles in one boot with 0 failures (P0-P5, 2026-10-26). P5 stopped that day on a speaker trip that turned out not to come from sleep ([NOTES](../device/cheetah/NOTES.md#2026-10-27-the-muted-speakers-were-the-open-loop-coil-estimate-not-sleep-the-static-was-the-boost-converter-the-earpiece-is-the-top-speaker)); resumed on 2026-11-01, it passed with 11 suspends and 0 failures, the speakers fine across each sleep. After its power-key test Hyprland ran neither power-key bind until `hyprctl reload`; the on-screen keyboard's virtual keyboard was reaching the hardware-key binds, which now ignore it ([#312](https://github.com/derekross/omarchy-mobile/pull/312), omamobile-shell 0.2.75; re-tested on the phone 2026-11-01, [SUSPEND-PLAN](../device/cheetah/SUSPEND-PLAN.md) P5 test h). Still open: NetworkManager drops Wi-Fi for each sleep and reconnects about 5 s after the wake. The toggle stays off by default until a day of use (P6) and a power-off from Linux (P7) have run. Wi-Fi traffic and a USB plug can't wake it, a few RTC cycles wake early on a PMIC interrupt not yet identified, and the modem has never run across a suspend. Deep sleep (SYS_SLEEP), which stock's standby numbers need, is research and not started | [SUSPEND-PLAN](../device/cheetah/SUSPEND-PLAN.md) | -| Fingerprint | works (on by default) | Google's HAL in a chroot behind a bridge and Trusty's fingerprint TA on our kernel (F3-F9), fprintd with our libfprint driver: enrollment from the shell, and the lock screen unlocks with a finger alongside the PIN pad or password, with the keyboard usable over the lock (F16b). A verify stays open across system sleep, and an enrollment interrupted by sleep fails cleanly (libfprint 1.6, 2026-10-19). From omamobile-fingerprint 0.1.14 it starts by default after provisioning: the runner makes its read-only copies itself, refuses to start when the TDP copy changed, and runs one storage proxy per boot (F19, 2026-11-02; the fresh-install checks T1-T3 are pending) | [FINGERPRINT-PLAN](../device/cheetah/FINGERPRINT-PLAN.md), [FINGERPRINT-RESEARCH](../device/cheetah/FINGERPRINT-RESEARCH.md) | +| Fingerprint | works (starts by default after provisioning; the automatic path is being tested) | Google's HAL in a chroot behind a bridge and Trusty's fingerprint TA on our kernel (F3-F9), fprintd with our libfprint driver: enrollment from the shell, and the lock screen unlocks with a finger alongside the PIN pad or password, with the keyboard usable over the lock (F16b). A verify stays open across system sleep, and an enrollment interrupted by sleep fails cleanly (libfprint 1.6, 2026-10-19). From omamobile-fingerprint 0.1.14 it starts by default after provisioning: the runner makes its read-only copies itself, refuses to start when the TDP copy changed, and runs one storage proxy per boot (F19, 2026-11-02; the fresh-install checks T1-T3 are pending) | [FINGERPRINT-PLAN](../device/cheetah/FINGERPRINT-PLAN.md), [FINGERPRINT-RESEARCH](../device/cheetah/FINGERPRINT-RESEARCH.md) | ## Wanted diff --git a/docs/INSTALL.md b/docs/INSTALL.md index aef250e48..7a9ec7663 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -199,7 +199,7 @@ tools/phone-ssh '(sleep 1; reboot-to omamobile) >/dev/null 2>&1 &' After the restart, Wi-Fi, Bluetooth, sound, haptics, the sensors and the cameras work. -**Fingerprint unlock works after this restart.** The phone offers "Add a fingerprint" (or find it later in Setup > Security > Fingerprint): touch the sensor under the bright circle until it's done, and the finger unlocks the phone alongside your PIN or password. Its first start writes the phone's secure storage (Trusty's area in the UFS RPMB), the same kind of write Android makes at a factory reset; before that it makes read-only copies of the data it needs from `persist` and the factory calibration (`mfg_data`), which it never writes. If those copies can't be made or later don't match, fingerprint stays off and the PIN unlocks. If fingerprint stops, restart the phone rather than the service. +**Fingerprint unlock starts automatically after this restart.** The phone offers "Add a fingerprint" (or find it later in Setup > Security > Fingerprint): touch the sensor under the bright circle until it's done, and the finger unlocks the phone alongside your PIN or password. Its first start writes the phone's secure storage (Trusty's area in the UFS RPMB), the same kind of write Android makes at a factory reset; before that it makes read-only copies of the data it needs from `persist` and the factory calibration (`mfg_data`), which it never writes. If those copies can't be made or later don't match, fingerprint stays off and the PIN unlocks. If fingerprint stops, restart the phone rather than the service. To keep fingerprint off, run `sudo systemctl mask omamobile-fp` before this restart (`disable` isn't enough). ## Getting updates @@ -226,7 +226,7 @@ Stock Android is still on slot A. fastboot reboot ``` -3. Android starts into its recovery screen, because its data was erased. Choose "Factory data reset", and Android starts as a new phone. Fingers enrolled on Omarchy Mobile don't carry over: enroll them again on Android, and again after you come back (reinstalling erases them). +3. Android starts into its recovery screen, because its data was erased. Choose "Factory data reset", and Android starts as a new phone. Fingers enrolled on Omarchy Mobile don't carry over: Android's setup asks for fingerprints as usual, and after you come back you enroll them again (reinstalling erases them). To remove Omarchy Mobile completely, flash Google's factory image for your phone with Google's own tools (the [Android Flash Tool](https://flash.android.com) or the `flash-all.sh` script in the factory image). Don't lock the bootloader afterwards unless you're sure both slots hold Google's images; if in doubt, ask in an issue first. diff --git a/docs/release-notes/2026-11-DRAFT.md b/docs/release-notes/2026-11-DRAFT.md index a02c7a4f6..d3510e135 100644 --- a/docs/release-notes/2026-11-DRAFT.md +++ b/docs/release-notes/2026-11-DRAFT.md @@ -37,7 +37,7 @@ From [docs/DEVICES.md](../DEVICES.md) on the release day: | GNSS | Location through GeoClue, with a quick-settings tile | | NFC | Reads and writes tags; a tag with a link opens it | | Cameras | Main, ultrawide and front through libcamera; the telephoto at fixed focus | -| Fingerprint | Works after provisioning: enrollment offered at setup, unlock on the lock screen | +| Fingerprint | Starts automatically after provisioning: enrollment offered at setup, unlock on the lock screen | | CPU | Frequency scaling and thermal zones | ### New in the last weeks @@ -60,7 +60,7 @@ From [docs/DEVICES.md](../DEVICES.md) on the release day: - **Cameras:** basic image quality (no Google ISP or tuning); the telephoto doesn't focus. - **Bluetooth:** headset calls (HFP) don't work yet. - **USB-C:** the phone is a USB device only (no host mode or role switch yet); after a replug, `omamobile-usb-rescue` reconnects it. -- **Fingerprint starts once per boot by design:** if it stops, restart the phone. Its first start writes the phone's secure storage (Trusty's area in the RPMB, the same kind of write as an Android factory reset); `persist` and `mfg_data` are only read. Fingers are enrolled again after a reinstall, and on Android if you go back. +- **Fingerprint starts once per boot by design:** if it stops, restart the phone. Its first start writes the phone's secure storage (Trusty's area in the RPMB, the same kind of write as an Android factory reset); `persist` and `mfg_data` are only read. Fingers are enrolled again after a reinstall. To keep it off, `sudo systemctl mask omamobile-fp`. - **Google's firmware is not included** and never will be: after installing, the bundle's `tools/phone-provision` extracts it from your own factory image for your phone (Wi-Fi, Bluetooth, haptics, speakers, cameras). ## Phones already running a development build