fingerprintd/implementations/main.cpp

// SPDX-License-Identifier: GPL-3.0-only
// SPDX-FileCopyrightText: Copyright (C) 2026 Catcrafts®

// lint-disable-file fixed-width-types
// lint-disable-file no-char-pointer
/*
fingerprintd — the daemon shell.

Everything that touches hardware lives here; the decisions live in
fingerprintd-core, which is tested without a phone.

Three threads:

  * the SUPPLICANT services QTEE's callbacks — the storage listeners and the
    credentials object. Nothing QTEE asks of us happens without it.
  * the WORKER owns the sensor rail, the QTEE session and the trustlet, and is
    the ONLY thread that invokes the trustlet. Every enrolment and every
    authentication runs here, serialised by construction.
  * the MAIN thread runs the GLib loop and speaks net.reactivated.Fprint. It
    never touches the trustlet; it posts jobs to the worker and receives
    results back through g_idle_add.

Why one long-lived process: a listener registration is held for the life of
the process and QTEE's listener table is global to the boot; one sensor reset
buys exactly one trustlet init; and fprintd's clients expect a device that is
already open when they ask. So the process that powers the sensor is the
process that holds the session and owns the bus name.
*/
// libqcomtee is a C library and its headers carry no extern "C" guard -- it
// has only ever been consumed from C. Without one every symbol would be
// C++-mangled and none would link.
//
// The headers pull in <stdarg.h>, <stdatomic.h> and <stdio.h>, and under
// libc++ those drag in C++ templates, which may not appear inside an
// extern "C" block. Including them first makes the nested includes no-ops.
#include <stdarg.h>
#include <stdio.h>
#include <stdatomic.h>
extern "C" {
#include <qcomtee_object.h>
#include <qcomtee_object_types.h>
#include <qcomtee_errno.h>
}

#include <gio/gio.h>
#include <glib-unix.h>

#include <linux/gpio.h>
#include <linux/bsg.h>
#include <scsi/sg.h>
#include <pthread.h>
#include <fcntl.h>
#include <pwd.h>
#include <signal.h>
#include <sys/ioctl.h>
#include <sys/time.h>
#include <unistd.h>
#include <errno.h>
#include <string.h>

import std;
import Fingerprintd;

namespace {

// Bumping this is what publishes a package: the registry answers 409 for a
// version it already has, which a build treats as a no-op.
constexpr const char* Version = "0.1.0";

bool g_verbose = false;
// 500 ms was the research harness's pace, chosen so a human could read the
// transcript scroll by. It is not a design. The matcher rejects the early
// frames of a correct press and matches several frames in (frames 3 and 8 in
// the acceptance run), so frames-per-press is what decides a press -- and a
// lift is only noticed on the NEXT frame, so it is also the latency a user
// feels. A frame costs four QTEE round trips regardless; the gap on top is
// pure delay.
int g_frameGapMs = 40;
int g_samples = 10;         // common.max_enrolling_samples, as shipped
std::string g_logDir = "/var/log/fingerprintd";
std::string g_stateDir = "/var/lib/fingerprintd";
int g_rescan = -1;          // -1 = leave the config's value alone

// What a press that ends with no terminal verdict means. At the stock rescan
// budget a wrong finger answers "not identified yet" on every frame and never
// yields a terminal frame, so its press is undecided at lift -- and the only
// way a client ever hears verify-no-match is to treat that as one. The cost is
// on the correct finger: a press that ran out of frames before the matcher
// reached a verdict is also reported as no-match. Under rescan=0 this cannot
// arise (every frame is terminal), so the knob only matters with a budget.
bool g_undecidedIsNoMatch = false;

// The namespace key the trustlet hashes into the SFS group's directory name.
// It defaults to Android's because that is what this device's existing store
// was written under. It does NOT isolate anything -- SET_ACTIVE_GROUP's path
// selects the group to read, but SAVE_DATA writes into the Android group
// regardless. Isolation comes from the SFS root, not from this.
std::string g_groupPath{fingerprintd::ta::GroupNamespacePath};
std::string g_taPath = "/lib/firmware/focal64.mbn";
std::string g_cfgPath = "/lib/firmware/fingerprintd.json";

qcomtee_object* g_root = QCOMTEE_OBJECT_NULL;

// Every run writes its own timestamped transcript. Not a convenience: a run
// whose result nobody recorded is a run that has to be repeated on a human's
// finger. And a SINGLE shared log path is worse than none -- the next run,
// including a quick control, destroys the interesting one, which is how the
// first successful authentication in this project was very nearly lost.
//
// Done at the file-descriptor level rather than by wrapping a stream, because
// std::println writes to stdout through C stdio: an ostream wrapper would
// capture nothing. Routing fd 1 through tee catches every line including the
// ones libqcomtee prints.
bool StartTranscript(const std::string& dir) {
    std::error_code ec;
    std::filesystem::create_directories(dir, ec);
    auto now = std::chrono::system_clock::now();
    std::string path = std::format("{}/{:%Y%m%d-%H%M%S}.log", dir,
                                   std::chrono::floor<std::chrono::seconds>(now));
    FILE* t = ::popen(std::format("tee {}", path).c_str(), "w");
    if (!t) return false;
    ::dup2(::fileno(t), 1);
    ::setvbuf(stdout, nullptr, _IOLBF, 0);
    std::println("transcript: {}", path);
    return true;
}

// tee_call_t's second parameter is `unsigned long` on glibc and `int` on musl
// (qcomtee_object.h keys it off __GLIBC__), so the signature has to match or
// the function pointer will not convert. The native build is glibc and the
// phone is musl, so both forms are compiled here.
#ifdef __GLIBC__
int TeeCall(int fd, unsigned long op, ...) {
#else
int TeeCall(int fd, int op, ...) {
#endif
    va_list ap;
    va_start(ap, op);
    void* arg = va_arg(ap, void*);
    va_end(ap);
    pthread_setcanceltype(PTHREAD_CANCEL_ASYNCHRONOUS, nullptr);
    int ret = ::ioctl(fd, static_cast<unsigned long>(op), arg);
    pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, nullptr);
    return ret;
}

// QTEE's callbacks are serviced here. Nothing QTEE asks of us happens without
// this running.
void* Supplicant(void*) {
    for (;;) {
        pthread_testcancel();
        if (qcomtee_object_process_one(g_root))
            break;
    }
    return nullptr;
}

std::uint64_t NowMs() {
    timeval tv{};
    ::gettimeofday(&tv, nullptr);
    return static_cast<std::uint64_t>(tv.tv_sec) * 1000
         + static_cast<std::uint64_t>(tv.tv_usec) / 1000;
}

// ---- The credentials object
//
// QTEE will not take the credentials blob directly on the Register path: it
// takes an object and calls back into it, twice, while our invoke is still in
// flight. Two ops, GET_LENGTH then READ_AT_OFFSET.
//
// libqcomtee ships one of these, but only by pulling in QCBOR to build the
// map. The map is thirteen bytes and lives in Fingerprintd:Tee under test, so
// this serves it and the library needs no dependency beyond libc.
struct CredentialsObject {
    qcomtee_object object;              // must be first: we cast between them
    std::vector<std::byte> blob;
    std::uint64_t lenStorage = 0;       // op 0's answer, pointed at not copied
};

void CredentialsRelease(qcomtee_object* object) {
    delete reinterpret_cast<CredentialsObject*>(object);
}

qcomtee_result_t CredentialsDispatch(qcomtee_object* object, qcomtee_op_t op,
                                     qcomtee_param* params, int num) {
    auto* self = reinterpret_cast<CredentialsObject*>(object);

    // On the CALLBACK path a QCOMTEE_UBUF_OUTPUT param arrives with
    // addr = NULL and size = the capacity QTEE will accept: the dispatcher
    // supplies the buffer, so the handler POINTS the param at storage of its
    // own and lets the framework marshal it. Writing through the incoming addr
    // is a null dereference, which is exactly how this crashed the first time
    // it ran against real QTEE.
    if (op == static_cast<qcomtee_op_t>(fingerprintd::tee::CredOp::GetLength)) {
        if (num != 1 || params[0].attr != QCOMTEE_UBUF_OUTPUT)
            return QCOMTEE_ERROR_INVALID;
        if (params[0].ubuf.size < fingerprintd::tee::CredLengthReplySize)
            return QCOMTEE_ERROR_INVALID;
        self->lenStorage = static_cast<std::uint64_t>(self->blob.size());
        params[0].ubuf.addr = &self->lenStorage;
        params[0].ubuf.size = sizeof(self->lenStorage);
        return QCOMTEE_OK;
    }

    if (op == static_cast<qcomtee_op_t>(fingerprintd::tee::CredOp::ReadAtOffset)) {
        if (num != 2 || params[0].attr != QCOMTEE_UBUF_INPUT
                     || params[1].attr != QCOMTEE_UBUF_OUTPUT)
            return QCOMTEE_ERROR_INVALID;
        // An INPUT param does carry a real address; only outputs arrive NULL.
        if (params[0].ubuf.size < sizeof(std::uint64_t) || !params[0].ubuf.addr)
            return QCOMTEE_ERROR_INVALID;
        std::uint64_t offset = 0;
        ::memcpy(&offset, params[0].ubuf.addr, sizeof(offset));

        auto plan = fingerprintd::tee::PlanRead(self->blob.size(), offset,
                                                params[1].ubuf.size);
        if (!plan.valid)
            return QCOMTEE_ERROR_INVALID;
        // Same again: point at the blob, do not copy into QTEE's buffer. The
        // storage has to outlive the dispatch, which the object owns.
        params[1].ubuf.addr = self->blob.data() + plan.offset;
        params[1].ubuf.size = plan.count;
        return QCOMTEE_OK;
    }

    return QCOMTEE_ERROR_INVALID;
}

qcomtee_object_ops g_credOps = {
    /* release   */ CredentialsRelease,
    /* dispatch  */ CredentialsDispatch,
    /* error     */ nullptr,
    /* supported */ nullptr,
};

qcomtee_object* MakeCredentials(std::uint32_t uid) {
    auto* c = new CredentialsObject{};
    c->blob = fingerprintd::tee::BuildCredentials(uid, NowMs());
    if (qcomtee_object_cb_init(&c->object, &g_credOps, g_root)) {
        delete c;
        return QCOMTEE_OBJECT_NULL;
    }
    return &c->object;
}

// ROOT op 2: hand QTEE a live credentials object and get a client env back.
// QTEE calls into the object while this invoke is outstanding, which is why
// the supplicant has to be running first.
qcomtee_object* GetClientEnv(std::uint32_t uid) {
    qcomtee_object* creds = MakeCredentials(uid);
    if (creds == QCOMTEE_OBJECT_NULL) {
        std::println(std::cerr, "credentials object init failed");
        return QCOMTEE_OBJECT_NULL;
    }
    qcomtee_param p[2] = {};
    p[0].attr = QCOMTEE_OBJREF_INPUT;
    p[0].object = creds;
    p[1].attr = QCOMTEE_OBJREF_OUTPUT;
    qcomtee_result_t result = 0;
    if (qcomtee_object_invoke(g_root,
                              static_cast<qcomtee_op_t>(fingerprintd::tee::ClientEnvOp),
                              p, 2, &result) || result) {
        std::println(std::cerr, "ROOT op {} failed, result={}",
                     static_cast<unsigned>(fingerprintd::tee::ClientEnvOp),
                     static_cast<int>(result));
        return QCOMTEE_OBJECT_NULL;
    }
    return p[1].object;
}

// IClientEnv op 0: open a service by UID on the env.
qcomtee_object* OpenService(qcomtee_object* env, std::uint32_t uid) {
    qcomtee_param p[2] = {};
    p[0].attr = QCOMTEE_UBUF_INPUT;
    p[0].ubuf.addr = &uid;
    p[0].ubuf.size = sizeof(uid);
    p[1].attr = QCOMTEE_OBJREF_OUTPUT;
    qcomtee_result_t result = 0;
    if (qcomtee_object_invoke(env, 0, p, 2, &result) || result) {
        std::println(std::cerr, "IClientEnv.open({}) failed, result={}", uid,
                     static_cast<int>(result));
        return QCOMTEE_OBJECT_NULL;
    }
    return p[1].object;
}

// ---- The storage listeners
//
// QTEE cannot reach a filesystem, so it calls back into the normal world for
// every template read and write. This serves those callbacks. The framing is
// Fingerprintd:Sfs; what lives here is the file I/O and the registration.
//
// READ-ONLY MODE EXISTS FOR A REASON. QTEE deletes a container whose keyed
// integrity tag does not verify, so a listener that serves bytes at the wrong
// offset does not merely fail -- it makes QTEE unlink an enrolled template.
// That is unrecoverable. Until a build has been shown to round-trip a
// container, it should serve read-only, where an unlink is refused with EROFS
// and the store cannot be damaged.
bool g_sfsReadOnly = true;
std::string g_sfsRoot = "/var/lib/fingerprintd/sfs";

struct ListenerObject {
    qcomtee_object object;          // must be first
    std::uint32_t id = 0;
    qcomtee_object* shared = QCOMTEE_OBJECT_NULL;
    std::array<std::array<std::byte, 64>, 8> outBufs{};
};

void ListenerRelease(qcomtee_object* object) {
    delete reinterpret_cast<ListenerObject*>(object);
}

// Serve one gpfile request out of the shared buffer, in place.
void ServeGpFile(std::span<std::byte> sb) {
    namespace sfs = fingerprintd::sfs;

    auto req = sfs::ParseRequest(sb);
    if (!req) {
        std::println("    gpfile: undecodable request");
        sfs::WriteReply(sb, EINVAL, 0);
        return;
    }
    if (req->op == sfs::OpConfigPathInit) {
        // Asked first, with an empty frame. The answer is LATCHED for the
        // whole boot, so an experiment on its value needs a fresh boot.
        if (g_verbose)
            std::println("    gpfile op 12 (path init) -> {}", sfs::ConfigPathInitReply);
        sfs::WriteConfigPathInitReply(sb);
        return;
    }

    auto full = sfs::ResolvePath(g_sfsRoot, req->root, req->path);
    if (!full) {
        std::println("    gpfile: refusing path '{}' under root {}", req->path, req->root);
        sfs::WriteReply(sb, EINVAL, 0);
        return;
    }

    switch (req->action) {
    case sfs::Action::Read: {
        if (g_verbose)
            std::println("    gpfile READ  {} off={} len={}", *full, req->offset, req->length);
        std::ifstream f(*full, std::ios::binary);
        if (!f) { sfs::WriteReply(sb, ENOENT, 0); return; }
        if (req->offset > 0) f.seekg(req->offset);
        std::size_t want = std::min<std::size_t>(req->length,
                                                 sfs::Capacity(sb, sfs::Action::Read));
        f.read(reinterpret_cast<char*>(sb.data() + sfs::ReadDataOff),
               static_cast<std::streamsize>(want));
        auto got = static_cast<std::uint32_t>(f.gcount());
        if (g_verbose)
            std::println("      -> errno=0 count={} (asked {}, capacity {})", got,
                         req->length, sfs::Capacity(sb, sfs::Action::Read));
        sfs::WriteReply(sb, 0, got);
        return;
    }
    case sfs::Action::Write: {
        std::println("    gpfile WRITE {} off={} len={}", *full, req->offset, req->length);
        if (g_sfsReadOnly) {
            std::println("      REFUSED: read-only");
            sfs::WriteReply(sb, EROFS, 0);
            return;
        }
        // The group directory may not exist yet -- a store with no enrolments
        // has no group at all, and open(O_CREAT) creates the file, never its
        // parent. Without this a first enrolment into a fresh store fails with
        // ENOENT, which QTEE reports as an I/O error indistinguishable from a
        // real storage fault.
        std::error_code ec;
        std::filesystem::create_directories(
            std::filesystem::path(*full).parent_path(), ec);

        // O_RDWR | O_CREAT | O_SYNC and never O_TRUNC: QTEE writes a container
        // as write(0,4096), write(4096,N), write(0,4096), so truncating on open
        // leaves 4096 bytes where a 258850-byte template belongs.
        int fd = ::open(full->c_str(), O_RDWR | O_CREAT | O_SYNC, 0600);
        if (fd < 0) { sfs::WriteReply(sb, errno, 0); return; }
        if (req->offset > 0 && ::lseek(fd, req->offset, SEEK_SET) < 0) {
            int e = errno; ::close(fd); sfs::WriteReply(sb, e, 0); return;
        }
        std::size_t want = std::min<std::size_t>(req->length,
                                                 sfs::Capacity(sb, sfs::Action::Write));
        std::size_t done = 0;
        int werr = 0;
        while (done < want) {   // short writes are real; the reference loops
            ssize_t n = ::write(fd, sb.data() + sfs::WriteDataOff + done, want - done);
            if (n < 0) { werr = errno; break; }
            if (n == 0) break;
            done += static_cast<std::size_t>(n);
        }
        ::fsync(fd);
        ::close(fd);
        std::println("      -> errno={} count={}", werr, done);
        sfs::WriteReply(sb, static_cast<std::uint32_t>(werr),
                        static_cast<std::uint32_t>(done));
        return;
    }
    case sfs::Action::Unlink:
        std::println("    gpfile UNLINK {}", *full);
        if (g_sfsReadOnly) {
            std::println("      REFUSED: read-only (this is what protects an enrolled template)");
            sfs::WriteReply(sb, EROFS, 0);
            return;
        }
        sfs::WriteReply(sb, ::unlink(full->c_str()) ? errno : 0, 0);
        return;
    case sfs::Action::Rename: {
        auto to = sfs::ResolvePath(g_sfsRoot, req->root, req->path2);
        std::println("    gpfile RENAME {} -> {}", *full, to ? *to : std::string("?"));
        if (g_sfsReadOnly || !to) { sfs::WriteReply(sb, EROFS, 0); return; }
        sfs::WriteReply(sb, ::rename(full->c_str(), to->c_str()) ? errno : 0, 0);
        return;
    }
    }
}

// ---- RPMB
//
// The anti-rollback half. QTEE will not trust a container until it has read
// its counter record out of the UFS device's replay-protected area, and it
// cannot reach the device itself. This serves that read, and the write.
//
// A WRITE advances a monotonic counter that can never be moved back, so it is
// refused unless explicitly enabled. Key programming is refused ALWAYS -- the
// RPMB key is one-time programmable and relaying such a frame destroys this
// part's RPMB permanently.
bool g_rpmbWrite = false;

// SECURITY PROTOCOL IN/OUT against the RPMB well-known LUN. Returns 0 on
// success, 1 on unit attention (retryable), -1 on error.
int SecurityProtocol(int fd, bool isIn, std::byte* buf, std::uint32_t len) {
    namespace rp = fingerprintd::rpmb;
    std::array<unsigned char, 12> cdb{};
    std::array<unsigned char, 64> sense{};

    cdb[0] = isIn ? 0xA2 : 0xB5;
    cdb[1] = rp::SecurityProtocolUfs;
    cdb[2] = (rp::SecurityProtocolSpecific >> 8) & 0xFF;
    cdb[3] = rp::SecurityProtocolSpecific & 0xFF;
    cdb[4] = 0;                       // INC_512 = 0: the length is in bytes
    cdb[6] = (len >> 24) & 0xFF;
    cdb[7] = (len >> 16) & 0xFF;
    cdb[8] = (len >> 8) & 0xFF;
    cdb[9] = len & 0xFF;

    sg_io_v4 io{};
    io.guard = 'Q';
    io.protocol = BSG_PROTOCOL_SCSI;
    io.subprotocol = BSG_SUB_PROTOCOL_SCSI_CMD;
    io.request_len = cdb.size();
    io.request = reinterpret_cast<std::uintptr_t>(cdb.data());
    io.max_response_len = sense.size();
    io.response = reinterpret_cast<std::uintptr_t>(sense.data());
    io.timeout = 15000;
    if (isIn) {
        io.din_xfer_len = len;
        io.din_xferp = reinterpret_cast<std::uintptr_t>(buf);
    } else {
        io.dout_xfer_len = len;
        io.dout_xferp = reinterpret_cast<std::uintptr_t>(buf);
    }

    if (::ioctl(fd, SG_IO, &io) < 0) {
        std::println("      SP{} ioctl failed: {}", isIn ? "I" : "O", ::strerror(errno));
        return -1;
    }
    if (io.driver_status || io.transport_status || io.device_status) {
        unsigned key = sense[2] & 0x0F;
        if (g_verbose)
            std::println("      SP{} status drv={} trans={} dev={} sense key={} asc=0x{:02x}/{:02x}",
                         isIn ? "I" : "O", io.driver_status, io.transport_status,
                         io.device_status, key, sense[12], sense[13]);
        // The RPMB LUN raises UNIT ATTENTION on the first command after a
        // reset and clears it by reporting it once. Retryable, not an error.
        return key == fingerprintd::rpmb::SenseKeyUnitAttention ? 1 : -1;
    }
    return 0;
}

int SecurityProtocolRetry(int fd, bool isIn, std::byte* buf, std::uint32_t len) {
    for (int t = 0; t < 4; t++) {
        int rc = SecurityProtocol(fd, isIn, buf, len);
        if (rc != 1) return rc;
    }
    return -1;
}

void ServeRpmb(std::span<std::byte> sb) {
    namespace rp = fingerprintd::rpmb;

    auto req = rp::ParseRequest(sb);
    if (!req) { rp::WriteReply(sb, rp::StatusRefused, 0); return; }
    if (g_verbose)
        std::println("    rpmb op=0x{:x} nblocks={} framesz={} dataoff=0x{:x}",
                     static_cast<unsigned>(req->op), req->nblocks, req->frameSize,
                     req->dataOff);

    if (!rp::FramesInBounds(sb, *req)) {
        std::println("    rpmb: frames out of bounds, refusing");
        rp::WriteReply(sb, rp::StatusRefused, 0);
        return;
    }

    // NEVER RELAYED, whatever the write policy says. The RPMB authentication
    // key is one-time programmable: reprogramming it destroys this part's RPMB
    // permanently and no reflash recovers it. QTEE has no legitimate reason to
    // send one.
    if (rp::AnyKeyProgramming(sb, *req)) {
        std::println("    *** REFUSED: RPMB KEY PROGRAMMING frame. Irreversible. ***");
        rp::WriteReply(sb, rp::StatusRefused, 0);
        return;
    }

    if (req->op == rp::Op::Write && !g_rpmbWrite) {
        std::println("    rpmb WRITE refused (advances an irreversible counter)");
        rp::WriteReply(sb, rp::StatusRefused, 0);
        return;
    }
    if (req->op != rp::Op::Read && req->op != rp::Op::Write) {
        rp::WriteReply(sb, rp::StatusRefused, 0);
        return;
    }

    int fd = ::open(std::string(rp::BsgDevice).c_str(), O_RDWR);
    if (fd < 0) {
        std::println("    rpmb: open {}: {}", rp::BsgDevice, ::strerror(errno));
        rp::WriteReply(sb, rp::StatusRefused, 0);
        return;
    }
    std::byte* frames = sb.data() + req->dataOff;
    std::uint32_t total = req->nblocks * static_cast<std::uint32_t>(rp::FrameSize);

    int rc = -1;
    if (req->op == rp::Op::Read) {
        // A read posts ONE request frame however large nblocks is, then
        // collects nblocks * 512 back.
        if (SecurityProtocolRetry(fd, false, frames, rp::FrameSize) == 0)
            rc = SecurityProtocolRetry(fd, true, frames, total);
    } else {
        // The authenticated write sequence, per chunk: the data frames out, a
        // Result Read Request out, the result frame back.
        //
        // req+0x14 is the chunk size, but it is not always usable: the
        // reference falls back to the whole block count when it is zero or
        // larger than nblocks. A remainder is refused rather than partially
        // committed -- a partial authenticated write leaves the store
        // inconsistent with a counter that cannot be moved back.
        std::uint32_t bpo = req->blocksPerOp;
        if (bpo == 0 || bpo > req->nblocks) bpo = req->nblocks;
        auto plan = rp::PlanChunks(req->nblocks, bpo);
        if (!plan.exact) {
            std::println("    rpmb: {} blocks is not a whole number of {}-block chunks"
                         " -- refusing", req->nblocks, bpo);
        } else {
            std::array<std::byte, rp::FrameSize> rrq{};
            rp::BuildResultReadRequest(rrq);
            rc = 0;
            for (std::uint32_t k = 0; k < plan.chunks && rc == 0; k++) {
                std::byte* chunk = frames + static_cast<std::size_t>(k)
                                 * bpo * rp::FrameSize;
                std::uint32_t bytes = bpo * static_cast<std::uint32_t>(rp::FrameSize);
                // The RESULT FRAME GOES BACK INTO THE SHARED BUFFER, at the
                // data offset -- QTEE reads it at req + req[0x0c], which is
                // exactly where the request frames were. Collecting it into a
                // local means QTEE never sees the device's answer and fails
                // the whole transaction with an I/O error, having already
                // committed the counter.
                std::byte* result = frames;
                if (SecurityProtocolRetry(fd, false, chunk, bytes) != 0 ||
                    SecurityProtocolRetry(fd, false, rrq.data(), rp::FrameSize) != 0 ||
                    SecurityProtocolRetry(fd, true, result, rp::FrameSize) != 0) {
                    rc = -1;
                    break;
                }
                std::span<const std::byte> rf(result, rp::FrameSize);
                std::uint16_t res = rp::ResultOf(rf);
                std::println("      rpmb write chunk {}/{}: result=0x{:04x} ({}) counter={}",
                             k + 1, plan.chunks, res, rp::ResultString(res),
                             rp::WriteCounterOf(rf));
                // Anything non-zero aborts rather than continuing into further
                // chunks: the device rejected the frame and the counter state
                // is not what we think it is.
                if (res != rp::ResultOk) rc = -1;
            }
        }
    }
    ::close(fd);

    if (rc != 0) {
        rp::WriteReply(sb, rp::StatusRefused, 0);
        return;
    }
    // +0x08 is an OUT parameter QTEE checks against what it expected to be
    // transferred; leaving the request's frame size there fails every
    // transaction. +0x0c is left exactly as the request supplied it.
    rp::WriteReply(sb, rp::StatusOk, rp::BytesTransferred(req->op, req->nblocks));
}

qcomtee_result_t ListenerDispatch(qcomtee_object* object, qcomtee_op_t op,
                                  qcomtee_param* params, int num) {
    auto* self = reinterpret_cast<ListenerObject*>(object);
    (void)op;

    for (int i = 0; i < num; i++) {
        switch (params[i].attr) {
        case QCOMTEE_UBUF_OUTPUT: {
            // addr arrives NULL on the callback path; point it at our own
            // storage. Zeros are the answer QTEE expects here.
            std::size_t want = std::min<std::size_t>(params[i].ubuf.size,
                                                     self->outBufs[0].size());
            if (i < 8) {
                self->outBufs[i].fill(std::byte{0});
                params[i].ubuf.addr = self->outBufs[i].data();
                params[i].ubuf.size = want;
            }
            break;
        }
        case QCOMTEE_OBJREF_OUTPUT:
            // MUST be set. cb_marshal_in leaves .object uninitialised and
            // marshal_out then calls typeof() on stack garbage -- a SIGSEGV in
            // the supplicant the moment QTEE first dispatches.
            params[i].object = QCOMTEE_OBJECT_NULL;
            break;
        default:
            break;
        }
    }

    // The request itself rides in the registered shared buffer, not in params.
    void* addr = qcomtee_memory_object_addr(self->shared);
    std::size_t size = qcomtee_memory_object_size(self->shared);
    if (addr) {
        std::span<std::byte> sb(static_cast<std::byte*>(addr), size);
        if (self->id == 0x7000)
            ServeGpFile(sb);
        else if (self->id == 0x2000)
            ServeRpmb(sb);
    }
    return QCOMTEE_OK;
}

qcomtee_object_ops g_listenerOps = {
    /* release   */ ListenerRelease,
    /* dispatch  */ ListenerDispatch,
    /* error     */ nullptr,
    /* supported */ nullptr,
};

// One callback object PER registration. Sharing one across registrations
// overwrites its id and buffer, and every multi-listener result taken that way
// is void -- six sessions of hypotheses rested on exactly that bug.
bool RegisterListener(qcomtee_object* env, std::uint32_t id, std::size_t bufSize) {
    qcomtee_object* svc = OpenService(env, fingerprintd::tee::UidListenerCbo);
    if (svc == QCOMTEE_OBJECT_NULL) return false;

    qcomtee_object* shared = QCOMTEE_OBJECT_NULL;
    if (qcomtee_memory_object_alloc(bufSize, g_root, &shared)) {
        std::println(std::cerr, "listener 0x{:x}: shared buffer alloc failed", id);
        return false;
    }
    auto* lo = new ListenerObject{};
    lo->id = id;
    lo->shared = shared;
    if (qcomtee_object_cb_init(&lo->object, &g_listenerOps, g_root)) {
        delete lo;
        return false;
    }

    std::uint32_t lid = id;
    qcomtee_param p[3] = {};
    p[0].attr = QCOMTEE_UBUF_INPUT;   p[0].ubuf.addr = &lid; p[0].ubuf.size = sizeof(lid);
    p[1].attr = QCOMTEE_OBJREF_INPUT; p[1].object = &lo->object;
    p[2].attr = QCOMTEE_OBJREF_INPUT; p[2].object = shared;
    qcomtee_result_t result = 0;
    if (qcomtee_object_invoke(svc, 0, p, 3, &result)) {
        std::println(std::cerr, "listener 0x{:x}: invoke failed", id);
        return false;
    }
    std::println("listener 0x{:<5x} sb={:<7} -> result={}{}", id, bufSize,
                 static_cast<int>(result),
                 result == 0 ? "  REGISTERED"
                 : static_cast<int>(result) == fingerprintd::tee::ResultIdAlreadyTaken
                   ? "  (id already taken)" : "");
    return result == 0;
}

// ---- The sensor rail
//
// GPIO v2 chardev ioctls directly: libgpiod is not on the phone and this is
// three lines. The chip is found by LABEL, never by index -- /dev/gpiochipN
// ordering is not stable and driving the wrong controller's pins is the kind
// of mistake that is not recoverable over ssh.
class Sensor {
public:
    ~Sensor() { PowerOff(); }

    bool Open() {
        namespace sn = fingerprintd::sensor;
        chip_ = FindChip(sn::ChipLabel);
        if (chip_ < 0) {
            std::println(std::cerr, "no gpiochip labelled '{}'", sn::ChipLabel);
            return false;
        }
        power_ = RequestLine(sn::PowerLine, GPIO_V2_LINE_FLAG_OUTPUT, "fpd-pwr");
        reset_ = RequestLine(sn::ResetLine, GPIO_V2_LINE_FLAG_OUTPUT, "fpd-rst");
        irq_   = RequestLine(sn::IrqLine,   GPIO_V2_LINE_FLAG_INPUT,  "fpd-irq");
        return power_ >= 0 && reset_ >= 0 && irq_ >= 0;
    }

    // Rail up, settle, release reset, settle. Both lines are driven low first
    // so a warm restart starts where a cold one does.
    bool PowerOn() {
        namespace sn = fingerprintd::sensor;
        if (!Set(power_, 0) || !Set(reset_, 0)) return false;
        if (!Set(power_, 1)) return false;
        std::this_thread::sleep_for(sn::PowerSettle);
        if (!Set(reset_, 1)) return false;
        std::this_thread::sleep_for(sn::ResetSettle);
        on_ = true;
        return true;
    }

    void PowerOff() {
        if (!on_) return;
        Set(reset_, 0);
        Set(power_, 0);
        on_ = false;
    }

    std::optional<int> ReadIrq() const { return Get(irq_); }

private:
    static int FindChip(std::string_view label) {
        for (int i = 0; i < 32; i++) {
            std::string path = std::format("/dev/gpiochip{}", i);
            int fd = ::open(path.c_str(), O_RDWR | O_CLOEXEC);
            if (fd < 0) continue;
            gpiochip_info info{};
            if (::ioctl(fd, GPIO_GET_CHIPINFO_IOCTL, &info) == 0
                && label == info.label
                && info.lines >= fingerprintd::sensor::MinChipLines) {
                std::println("gpiochip '{}' is {} ({} lines)", info.label, path,
                             info.lines);
                return fd;
            }
            ::close(fd);
        }
        return -1;
    }

    int RequestLine(unsigned line, std::uint64_t flags, const char* consumer) {
        // The guard, enforced where the line is actually opened rather than
        // only asserted in the core. gpio8-11 are XPU-protected and touching
        // one is an immediate SError, not an error return.
        if (!fingerprintd::sensor::IsSafeLine(line)) {
            std::println(std::cerr,
                         "REFUSING to open gpio{}: XPU-protected fingerprint SPI", line);
            return -1;
        }
        gpio_v2_line_request req{};
        req.offsets[0] = line;
        req.num_lines = 1;
        req.config.flags = flags;
        std::snprintf(req.consumer, sizeof(req.consumer), "%s", consumer);
        if (::ioctl(chip_, GPIO_V2_GET_LINE_IOCTL, &req) < 0) {
            std::println(std::cerr, "gpio{} request failed: {}", line, ::strerror(errno));
            return -1;
        }
        return req.fd;
    }

    static bool Set(int fd, int v) {
        if (fd < 0) return false;
        gpio_v2_line_values vals{};
        vals.mask = 1;
        vals.bits = v ? 1 : 0;
        return ::ioctl(fd, GPIO_V2_LINE_SET_VALUES_IOCTL, &vals) == 0;
    }

    static std::optional<int> Get(int fd) {
        if (fd < 0) return std::nullopt;
        gpio_v2_line_values vals{};
        vals.mask = 1;
        if (::ioctl(fd, GPIO_V2_LINE_GET_VALUES_IOCTL, &vals) < 0) return std::nullopt;
        return static_cast<int>(vals.bits & 1);
    }

    int chip_ = -1, power_ = -1, reset_ = -1, irq_ = -1;
    bool on_ = false;
};

// ---- The trustlet
//
// The loader is IQSEEComCompatAppLoader (UID 122): op 1 loadFromBuffer, op 2
// lookupTA. A stale instance from a crashed run is unloaded first, which is
// what stops a bad experiment costing a reboot.
constexpr const char* TaName = "focal64";

void UnloadStale(qcomtee_object* loader) {
    qcomtee_param p[3] = {};
    std::array<std::byte, 4> ob{};
    p[0].attr = QCOMTEE_UBUF_INPUT;
    p[0].ubuf.addr = const_cast<char*>(TaName);
    p[0].ubuf.size = std::strlen(TaName);
    p[1].attr = QCOMTEE_UBUF_OUTPUT;
    p[1].ubuf.addr = ob.data();
    p[1].ubuf.size = ob.size();
    p[2].attr = QCOMTEE_OBJREF_OUTPUT;
    qcomtee_result_t result = 0;
    if (qcomtee_object_invoke(loader, 2, p, 3, &result) || result) {
        std::println("lookupTA('{}') -> result={} (nothing to unload)", TaName,
                     static_cast<int>(result));
        return;
    }
    if (!qcomtee_object_invoke(p[2].object, 2, nullptr, 0, &result))
        std::println("unloaded a stale '{}' -> result={}", TaName, static_cast<int>(result));
    qcomtee_object_refs_dec(p[2].object);
}

qcomtee_object* LoadTrustlet(qcomtee_object* loader, const std::string& path) {
    UnloadStale(loader);

    std::ifstream f(path, std::ios::binary);
    if (!f) {
        std::println(std::cerr, "cannot open {}", path);
        return QCOMTEE_OBJECT_NULL;
    }
    std::vector<char> image((std::istreambuf_iterator<char>(f)),
                            std::istreambuf_iterator<char>());
    if (image.empty()) {
        std::println(std::cerr, "{} is empty", path);
        return QCOMTEE_OBJECT_NULL;
    }

    std::array<char, 128> distName{};
    qcomtee_param p[4] = {};
    p[0].attr = QCOMTEE_UBUF_INPUT;
    p[0].ubuf.addr = image.data();
    p[0].ubuf.size = image.size();
    p[1].attr = QCOMTEE_UBUF_INPUT;
    p[1].ubuf.addr = const_cast<char*>(TaName);
    p[1].ubuf.size = std::strlen(TaName);
    p[2].attr = QCOMTEE_UBUF_OUTPUT;
    p[2].ubuf.addr = distName.data();
    p[2].ubuf.size = distName.size();
    p[3].attr = QCOMTEE_OBJREF_OUTPUT;
    qcomtee_result_t result = 0;
    if (qcomtee_object_invoke(loader, 1, p, 4, &result) || result) {
        std::println(std::cerr, "loadFromBuffer failed, result={}",
                     static_cast<int>(result));
        return QCOMTEE_OBJECT_NULL;
    }
    std::println("trustlet loaded from {} ({} bytes), distName='{}'", path,
                 image.size(), distName.data());
    return p[3].object;
}

// sendRequest is op 0 with arity 0x0424: four input buffers, two output, four
// object slots. The request and response buffers go in and come back out; the
// trustlet's own return code rides in the returned request's header.
struct CommandResult {
    bool invoked = false;
    qcomtee_result_t result = 0;
    std::int32_t rc = 0;
    std::int32_t metric = 0;
    // Only meaningful for REPORT_EVENT: the matcher's verdict rides in the
    // returned request's payload.
    std::uint32_t gid = 0;
    std::uint32_t fid = 0;
    std::int32_t samplesRemaining = -1;

    bool Ok() const { return invoked && result == 0 && rc == 0; }
};

CommandResult SendCommand(qcomtee_object* app, fingerprintd::ta::Cmd cmd,
                          std::span<const std::byte> payload) {
    namespace ta = fingerprintd::ta;
    namespace tee = fingerprintd::tee;
    // Only ever called from the worker thread, hence static.
    static std::vector<std::byte> req(8192), rsp(16384), reqOut(8192), rspOut(16384);
    std::ranges::fill(rsp, std::byte{0});
    std::ranges::fill(reqOut, std::byte{0});
    std::ranges::fill(rspOut, std::byte{0});
    ta::BuildRequest(req, cmd, payload);

    // CAPTURE_IMAGE's flags word sits at payload+0x18, PAST the declared
    // length of 0x14 -- the trustlet range-checks the length to exactly that
    // and reads the flags anyway. Without bit 1 or bit 30 it skips
    // preprocessing, the classifier and the enrol grouper entirely and returns
    // success having done nothing but a raw scan.
    if (cmd == ta::Cmd::CaptureImage) {
        for (std::size_t i = 0; i < 4; i++)
            req[ta::ReqPayloadOff + ta::CaptureFlagsOff + i] =
                static_cast<std::byte>((ta::CaptureFlagsEnrol >> (8 * i)) & 0xFF);
    }

    std::uint32_t is64 = 1;
    qcomtee_param p[10] = {};
    p[0].attr = QCOMTEE_UBUF_INPUT;  p[0].ubuf.addr = req.data();    p[0].ubuf.size = req.size();
    p[1].attr = QCOMTEE_UBUF_INPUT;  p[1].ubuf.addr = rsp.data();    p[1].ubuf.size = rsp.size();
    p[2].attr = QCOMTEE_UBUF_INPUT;  p[2].ubuf.addr = nullptr;       p[2].ubuf.size = 0;
    p[3].attr = QCOMTEE_UBUF_INPUT;  p[3].ubuf.addr = &is64;         p[3].ubuf.size = sizeof(is64);
    p[4].attr = QCOMTEE_UBUF_OUTPUT; p[4].ubuf.addr = reqOut.data(); p[4].ubuf.size = reqOut.size();
    p[5].attr = QCOMTEE_UBUF_OUTPUT; p[5].ubuf.addr = rspOut.data(); p[5].ubuf.size = rspOut.size();
    for (int i = 6; i < 10; i++) {
        p[i].attr = QCOMTEE_OBJREF_INPUT;
        p[i].object = QCOMTEE_OBJECT_NULL;
    }

    // A capture needs a real shared memory REGION or the trustlet answers
    // -201: it reads an output-buffer pointer out of payload+0x00, and QTEE
    // only patches an address in there if we name the location in
    // embeddedBufOffsets (IB2) and hand it the region in an object slot.
    //
    // Two traps: the offsets array applies to EVERY command in a run, so it is
    // scoped to this one command -- patching a pointer into SYNC_CONFIG's
    // request breaks it. And an invoke CONSUMES its input objects, so the
    // region is allocated fresh each time.
    qcomtee_object* region = QCOMTEE_OBJECT_NULL;
    std::uint32_t offsets = tee::EmbeddedBufOffsetValue;
    if (cmd == static_cast<ta::Cmd>(tee::RegionScopedToCommand)) {
        if (qcomtee_memory_object_alloc(tee::CaptureRegionSize, g_root, &region)) {
            std::println(std::cerr, "  memory region alloc failed");
            region = QCOMTEE_OBJECT_NULL;
        } else {
            std::memset(qcomtee_memory_object_addr(region), 0,
                        qcomtee_memory_object_size(region));
            p[2].ubuf.addr = &offsets;
            p[2].ubuf.size = sizeof(offsets);
            p[6].object = region;
        }
    }

    CommandResult out;
    if (qcomtee_object_invoke(app, tee::AppSendRequestOp, p, 10, &out.result)) {
        if (region != QCOMTEE_OBJECT_NULL)
            qcomtee_memory_object_release(region);
        return out;
    }
    out.invoked = true;
    out.rc = ta::ResultCode(reqOut);
    out.metric = ta::CaptureMetric(reqOut);
    if (cmd == ta::Cmd::ReportEvent) {
        out.gid = ta::MatchedGid(reqOut);
        out.fid = ta::MatchedFid(reqOut);
        out.samplesRemaining = ta::SamplesRemaining(reqOut);
    }
    return out;
}

void Report(fingerprintd::ta::Cmd cmd, const CommandResult& r) {
    namespace ta = fingerprintd::ta;
    if (!r.invoked) {
        std::println("  CMD 0x{:04x} -> INVOKE FAILED", static_cast<unsigned>(cmd));
        return;
    }
    // A POSITIVE rc is not an error code. ENUMERATE returns the template
    // count there, so running it through the error table prints "unknown" for
    // a perfectly good answer.
    if (r.rc > 0)
        std::println("  CMD 0x{:04x} -> result={} rc={}", static_cast<unsigned>(cmd),
                     static_cast<int>(r.result), r.rc);
    else
        std::println("  CMD 0x{:04x} -> result={} rc={} ({})", static_cast<unsigned>(cmd),
                     static_cast<int>(r.result), r.rc, ta::StrError(r.rc));
}

// =============================================================================
// The session: everything from a cold /dev/tee0 to a calibrated sensor, and
// the enrol and verify loops that run against it. WORKER THREAD ONLY.
// =============================================================================
class Session {
public:
    // The whole bring-up. Fails loudly at the first step that does not
    // answer; nothing after a failure is attempted.
    bool Start() {
        namespace tee = fingerprintd::tee;
        namespace ta = fingerprintd::ta;

        std::string dev(tee::DevTee);
        g_root = qcomtee_object_root_init(dev.c_str(), TeeCall, nullptr, nullptr);
        if (g_root == QCOMTEE_OBJECT_NULL) {
            std::println(std::cerr, "root object on {}: {}", tee::DevTee, ::strerror(errno));
            return false;
        }
        std::println("root object on {}", tee::DevTee);

        if (pthread_create(&supplicant_, nullptr, Supplicant, nullptr) != 0) {
            std::println(std::cerr, "supplicant thread failed to start");
            return false;
        }

        std::uint32_t uid = ::getuid();
        env_ = GetClientEnv(uid);
        if (env_ == QCOMTEE_OBJECT_NULL) return false;
        std::println("client env obtained (uid {})", uid);

        // Register the storage listeners BEFORE loading the trustlet, so any
        // storage QTEE wants during init has somewhere to go.
        for (const auto& l : tee::Listeners) {
            if (l.id == 10) continue;   // never called on the fingerprint path
            if (!RegisterListener(env_, l.id, l.bufferSize)) return false;
        }
        std::println("SFS root {} ({})", g_sfsRoot, g_sfsReadOnly ? "READ-ONLY" : "writable");

        qcomtee_object* loader = OpenService(env_, tee::UidQseecomCompatAppLoader);
        if (loader == QCOMTEE_OBJECT_NULL) return false;
        app_ = LoadTrustlet(loader, g_taPath);
        if (app_ == QCOMTEE_OBJECT_NULL) return false;

        if (!SyncConfig()) return false;

        // The sensor, and the init chain that needs it powered.
        if (!sensor_.Open()) {
            std::println(std::cerr, "sensor lines unavailable");
            return false;
        }
        if (!sensor_.PowerOn()) {
            std::println(std::cerr, "sensor power-up failed");
            return false;
        }
        std::println("sensor powered, reset released");

        // Every step answers rc=0 on a healthy sensor and the last one is not
        // optional: without SYNC_STATISTICS the trustlet's g_statistics stays
        // NULL and the first enrol frame that gets far enough writes through
        // it. One reset buys one init: if this fails the rail has to go down
        // and come back up, re-running the chain answers -205.
        for (ta::Cmd c : ta::InitChain) {
            std::vector<std::byte> payload;
            if (c == ta::Cmd::WorkMode) {
                payload.assign(0x10, std::byte{0});
                payload[0] = static_cast<std::byte>(
                    static_cast<std::uint32_t>(ta::WorkMode::WaitTouch));
            } else if (c == ta::Cmd::SyncStatistics) {
                payload.assign(ta::SyncStatisticsPayloadSize, std::byte{0});
            }
            auto r = SendCommand(app_, c, payload);
            Report(c, r);
            if (!r.Ok()) {
                if (r.rc == fingerprintd::sensor::RcDeviceNotFound)
                    std::println(std::cerr, "  -205: a second init in one power cycle");
                return false;
            }
        }

        // With the sensor initialised and a region supplied, a capture returns
        // a real metric. The idle floor is the only meaningful reference: the
        // metric is per frame and drifts, so a fixed threshold is wrong by
        // construction.
        for (std::size_t i = 0; i < fingerprintd::engine::Baseline::DefaultSamples; i++) {
            std::vector<std::byte> cap(ta::CaptureDeclaredLen);
            ta::BuildCapturePayload(cap);
            auto c = SendCommand(app_, ta::Cmd::CaptureImage, cap);
            if (!c.invoked || c.result != 0) {
                Report(ta::Cmd::CaptureImage, c);
                std::println(std::cerr, "capture failed during calibration");
                return false;
            }
            baseline_.Observe(c.metric);
        }
        if (!baseline_.Ready()) {
            std::println(std::cerr, "baseline did not calibrate (floor stayed 0)");
            return false;
        }
        std::println("idle floor = {}, finger threshold = {}", baseline_.Floor(),
                     baseline_.Threshold());
        return true;
    }

    void Stop() {
        sensor_.PowerOff();
        if (supplicant_) {
            pthread_cancel(supplicant_);
            pthread_join(supplicant_, nullptr);
            supplicant_ = 0;
        }
    }

    // Select a group and count what loads. A template reload needs the init
    // chain to have run first -- Start() guarantees that.
    int SetActiveGroup(std::uint32_t gid) {
        namespace ta = fingerprintd::ta;
        auto sag = ta::BuildSetActiveGroup(gid, g_groupPath);
        std::println("SET_ACTIVE_GROUP gid={}", gid);
        auto g = SendCommand(app_, ta::Cmd::SetActiveGroup, sag);
        Report(ta::Cmd::SetActiveGroup, g);
        auto e = SendCommand(app_, ta::Cmd::Enumerate, {});
        Report(ta::Cmd::Enumerate, e);
        std::println("  templates loaded: {}", e.rc);
        gid_ = gid;
        return e.invoked ? e.rc : -1;
    }

    // ---- Enrolment
    //
    // One sample per PRESS: touch on the rising edge, release on the falling
    // one, nothing in between. `onStage(accepted, total)` fires on each
    // accepted sample; `onRetry()` when a press yielded none.
    struct EnrolOutcome {
        bool completed = false;
        bool cancelled = false;
        bool saved = false;
        std::uint32_t fid = 0;
        std::string why;
    };

    EnrolOutcome Enrol(std::uint32_t gid, std::atomic<bool>& cancel,
                       const std::function<void(int, int)>& onStage,
                       const std::function<void()>& onRetry,
                       int maxFrames) {
        namespace ta = fingerprintd::ta;
        namespace en = fingerprintd::engine;
        EnrolOutcome out;

        if (g_sfsReadOnly || !g_rpmbWrite) {
            out.why = "store is read-only or RPMB writes disabled";
            return out;
        }
        if (gid != gid_) SetActiveGroup(gid);

        // Stock's opening sequence. AUTHENTICATE is what arms the capture
        // session; CANCEL and RESET_LOCKOUT bracket it.
        std::vector<std::byte> au(ta::AuthPayloadSize);
        ta::BuildAuthPayload(au, 1, 0);
        SendCommand(app_, ta::Cmd::Cancel, {});
        SendCommand(app_, ta::Cmd::ResetLockout, {});
        SendCommand(app_, ta::Cmd::Authenticate, au);
        SendCommand(app_, ta::Cmd::Cancel, {});
        SendCommand(app_, ta::Cmd::ResetLockout, {});
        SendCommand(app_, ta::Cmd::PreEnroll, {});
        SendCommand(app_, ta::Cmd::Authenticate, au);
        SendCommand(app_, ta::Cmd::Cancel, {});

        // The token is all zero: with trustlet.enable_trusted_enrollment false
        // the trustlet skips the version check, the challenge compare and the
        // HMAC verify outright. The u32 at +69 is the GID this enrolment lands
        // under.
        std::vector<std::byte> tok(ta::EnrollPayloadSize);
        ta::BuildEnrollPayload(tok, gid);
        auto er = SendCommand(app_, ta::Cmd::Enroll, tok);
        Report(ta::Cmd::Enroll, er);
        if (!er.Ok()) { out.why = "ENROLL refused"; return out; }
        std::println("enrolling gid={}", gid);

        en::TouchTracker tracker;
        en::EnrolSession enrol(g_samples);
        int lastAccepted = 0;
        bool pressHadTouch = false;
        for (int i = 0; i < maxFrames && !enrol.Complete() && !cancel; i++) {
            std::vector<std::byte> q(0x10, std::byte{0});
            SendCommand(app_, ta::Cmd::QueryEventStatus, q);

            std::vector<std::byte> cap(ta::CaptureDeclaredLen);
            ta::BuildCapturePayload(cap);
            auto c = SendCommand(app_, ta::Cmd::CaptureImage, cap);
            bool finger = baseline_.IsFinger(c.metric);

            for (ta::Event ev : tracker.Observe(finger, en::Mode::Enrol)) {
                std::vector<std::byte> evbuf(ta::EventContextSize);
                ta::BuildEventContext(evbuf, { .event = ev });
                // Poisoned so an unwritten fid can be told from a zero one.
                ta::PoisonFid(evbuf);
                auto r = SendCommand(app_, ta::Cmd::ReportEvent, evbuf);
                if (!r.invoked) continue;
                if (ev == ta::Event::FingerTouched) {
                    pressHadTouch = true;
                    // Only the event that runs the enrol path reports a real
                    // count. A release leaves the field at 0, which reads
                    // exactly like "finished".
                    enrol.Observe(r.samplesRemaining, true);
                    if (r.fid != 0 && r.fid != ta::FidPoison) out.fid = r.fid;
                    std::println("  touch: rem={} fid={:#x}", r.samplesRemaining, r.fid);
                }
                if (ev == ta::Event::FingerReleased && pressHadTouch) {
                    // The press is over. Did it move the count?
                    if (enrol.Accepted() > lastAccepted) {
                        lastAccepted = enrol.Accepted();
                        onStage(enrol.Accepted(), enrol.Total());
                    } else {
                        onRetry();
                    }
                    pressHadTouch = false;
                }
            }
            SendCommand(app_, ta::Cmd::QueryEventStatus, q);
            std::this_thread::sleep_for(std::chrono::milliseconds(g_frameGapMs));
        }
        // A final press that completed the count has no release yet.
        if (enrol.Complete() && enrol.Accepted() > lastAccepted)
            onStage(enrol.Accepted(), enrol.Total());

        if (cancel) {
            SendCommand(app_, ta::Cmd::Cancel, {});
            out.cancelled = true;
            out.why = "cancelled";
            return out;
        }
        std::println("samples: {} of {} accepted", enrol.Accepted(), enrol.Total());
        if (!enrol.Complete()) {
            out.why = "ran out of frames";
            return out;
        }
        out.completed = true;

        SendCommand(app_, ta::Cmd::PostEnroll, {});
        std::vector<std::byte> sd(0x10, std::byte{0});
        for (std::size_t k = 0; k < 4; k++)
            sd[k] = static_cast<std::byte>((ta::SaveMaskTemplate >> (8 * k)) & 0xFF);
        auto sv = SendCommand(app_, ta::Cmd::SaveData, sd);
        Report(ta::Cmd::SaveData, sv);
        out.saved = sv.Ok();
        if (!out.saved) out.why = std::format("SAVE_DATA rc={}", sv.rc);
        return out;
    }

    // ---- Verification
    //
    // The unit of decision is a PRESS, not a frame. A frame is one of three
    // things -- release (poison intact), rescan (rc=-11), match/reject -- and
    // within one press the matcher may reject early frames and match a later
    // one, so a press is judged when the finger LIFTS: any match wins; only
    // rejections means no-match; no terminal frame at all means undecided,
    // and scanning continues into the next press.
    //
    // That last case is why the rescan budget matters here. At the stock
    // budget a wrong finger answers "not identified yet" on every frame and
    // never yields a terminal rejection, so its presses are all undecided and
    // a client waits forever -- fprintd's PAM module needs a verify-no-match
    // to deny or retry. With max_authentication_rescan_times at 0 every frame
    // is terminal and every press decides. A wrong finger stops being a
    // silent wait.
    struct VerifyOutcome {
        bool decided = false;
        bool matched = false;
        bool cancelled = false;
        std::uint32_t fid = 0;
        int presses = 0;
        int frames = 0;
    };

    VerifyOutcome Verify(std::uint32_t gid, std::atomic<bool>& cancel, int maxFrames) {
        namespace ta = fingerprintd::ta;
        namespace en = fingerprintd::engine;
        VerifyOutcome out;

        if (gid != gid_) SetActiveGroup(gid);

        // AUTHENTICATE arms the scan session. Its gid must match the active
        // group or the trustlet answers -200.
        std::vector<std::byte> au(ta::AuthPayloadSize);
        ta::BuildAuthPayload(au, 1, gid);
        auto a = SendCommand(app_, ta::Cmd::Authenticate, au);
        Report(ta::Cmd::Authenticate, a);
        if (!a.Ok()) return out;

        en::TouchTracker tracker;
        bool inPress = false, pressMatched = false, pressRejected = false;
        int pressFrames = 0, rescans = 0;
        std::uint32_t pressFid = 0;
        auto t0 = std::chrono::steady_clock::now();
        auto msSince = [&](auto t) {
            return std::chrono::duration_cast<std::chrono::milliseconds>(
                std::chrono::steady_clock::now() - t).count();
        };

        // The reference frame loop is {QUERY, CAPTURE, REPORT, QUERY, REPORT}.
        // The trailing query acknowledges the trustlet's event state; without
        // it, after the first verdict every later frame answers "not
        // identified yet" forever.
        for (int i = 0; i < maxFrames && !cancel && !out.decided; i++) {
            std::vector<std::byte> q(0x10, std::byte{0});
            SendCommand(app_, ta::Cmd::QueryEventStatus, q);

            std::vector<std::byte> cap(ta::CaptureDeclaredLen);
            ta::BuildCapturePayload(cap);
            auto c = SendCommand(app_, ta::Cmd::CaptureImage, cap);
            bool finger = baseline_.IsFinger(c.metric);
            fingerPresent_.store(finger);
            out.frames++;

            std::string note;
            bool rising = finger && !inPress;
            if (rising) {
                inPress = true; pressMatched = false; pressRejected = false;
                pressFrames = 0; rescans = 0; pressFid = 0;
                out.presses++;
                // The frame that detected the finger is the finger LANDING --
                // partial contact, and the frame that rejects most often.
                // Capture once more now that it has settled, so the image the
                // matcher sees on the first report is a real one. One capture,
                // ~50 ms, on the frame that decides every quick tap.
                auto c2 = SendCommand(app_, ta::Cmd::CaptureImage, cap);
                if (c2.invoked) { c = c2; note += " recap"; }
            }
            for (ta::Event ev : tracker.Observe(finger, en::Mode::Authenticate)) {
                std::vector<std::byte> evbuf(ta::EventContextSize);
                ta::BuildEventContext(evbuf, { .event = ev });
                // A zero-initialised buffer cannot tell "the matcher never
                // ran" from "the matcher ran and rejected" -- the failure path
                // writes zero there too.
                ta::PoisonFid(evbuf);
                auto r = SendCommand(app_, ta::Cmd::ReportEvent, evbuf);
                if (!r.invoked) continue;
                ta::Verdict v = ta::Classify(r.rc, r.fid);
                switch (v) {
                case ta::Verdict::Match:            pressMatched = true; pressFid = r.fid; note += " MATCH"; break;
                case ta::Verdict::Rejected:         pressRejected = true; note += " rej"; break;
                case ta::Verdict::NotIdentifiedYet: rescans++; note += " -11"; break;
                case ta::Verdict::MatcherNeverRan:  break;
                }
                if (ev == ta::Event::FingerReleased && inPress) {
                    // The press is over: judge it.
                    inPress = false;
                    if (pressMatched) {
                        out.decided = true; out.matched = true; out.fid = pressFid;
                    } else if (pressRejected || (g_undecidedIsNoMatch && pressFrames > 0)) {
                        out.decided = true; out.matched = false;
                    }
                    std::println("  press {}: {} frames, {} rescans -> {}", out.presses, pressFrames,
                                 rescans, pressMatched ? std::format("MATCH fid={}", pressFid)
                                        : pressRejected ? "NO MATCH"
                                        : out.decided ? "NO MATCH (undecided at lift)" : "undecided");
                }
            }
            if (finger) pressFrames++;
            // A press that matched is decided the moment it does; do not make
            // the user keep holding for a release.
            if (pressMatched && !out.decided) {
                out.decided = true; out.matched = true; out.fid = pressFid;
                std::println("  press {}: {} frames -> MATCH fid={}", out.presses, pressFrames, pressFid);
            }
            SendCommand(app_, ta::Cmd::QueryEventStatus, q);
            if (g_verbose) {
                // The IRQ line alongside the metric: if it tracks the finger
                // under an armed session, lift detection can become an edge
                // wait instead of a poll.
                auto irq = sensor_.ReadIrq();
                std::println("  frame {:3} @{:5}ms: metric={:<4}{} irq={}{}", i + 1,
                             msSince(t0), c.metric, finger ? " FINGER" : "       ",
                             irq ? std::to_string(*irq) : "?", note);
            }
            std::this_thread::sleep_for(std::chrono::milliseconds(g_frameGapMs));
        }
        fingerPresent_.store(false);
        std::println("  verify loop: {} frames in {} ms ({} ms/frame incl. {} ms gap)",
                     out.frames, msSince(t0),
                     out.frames ? msSince(t0) / out.frames : 0, g_frameGapMs);
        if (cancel) {
            SendCommand(app_, ta::Cmd::Cancel, {});
            out.cancelled = true;
        }
        return out;
    }

    bool FingerPresent() const { return fingerPresent_.load(); }
    int EnrolStages() const { return g_samples; }
    qcomtee_object* App() const { return app_; }

private:
    bool SyncConfig() {
        namespace ta = fingerprintd::ta;
        std::ifstream cf(g_cfgPath);
        if (!cf) {
            std::println(std::cerr, "cannot open config {}", g_cfgPath);
            return false;
        }
        std::string json((std::istreambuf_iterator<char>(cf)), std::istreambuf_iterator<char>());

        // common.max_authentication_rescan_times bounds how many frames the
        // matcher may answer "not identified yet" before it must produce a
        // verdict. MEASUREMENT ONLY: a rate taken with 0 is a per-frame figure
        // with the retry mechanism disabled, not a shipping reject rate.
        if (g_rescan >= 0) {
            auto at = json.find("\"common\":{");
            if (at == std::string::npos) at = json.find("\"common\": {");
            if (at != std::string::npos) {
                auto brace = json.find('{', at);
                json.insert(brace + 1,
                            std::format("\"max_authentication_rescan_times\":{},", g_rescan));
                std::println("forcing max_authentication_rescan_times={} (MEASUREMENT ONLY)",
                             g_rescan);
            }
        }
        // The trustlet wants the terminating NUL counted.
        std::vector<std::byte> cfg(json.size() + 1, std::byte{0});
        for (std::size_t i = 0; i < json.size(); i++)
            cfg[i] = static_cast<std::byte>(json[i]);
        auto r = SendCommand(app_, ta::Cmd::SyncConfig, cfg);
        Report(ta::Cmd::SyncConfig, r);
        return r.Ok();
    }

    qcomtee_object* env_ = QCOMTEE_OBJECT_NULL;
    qcomtee_object* app_ = QCOMTEE_OBJECT_NULL;
    pthread_t supplicant_ = 0;
    Sensor sensor_;
    fingerprintd::engine::Baseline baseline_;
    std::uint32_t gid_ = 0xFFFFFFFF;
    std::atomic<bool> fingerPresent_{false};
};

// =============================================================================
// Worker: the one thread that talks to the trustlet. The main thread posts
// jobs; results and progress come back through the GLib main loop.
// =============================================================================
struct Job {
    enum class Kind { Claim, Enroll, Verify } kind;
    std::uint32_t uid = 0;
    std::string finger;
    GDBusMethodInvocation* invocation = nullptr;   // Claim replies asynchronously
};

// Everything the worker sends back to the main thread. Delivered by g_idle_add
// so the D-Bus emission happens on the thread that owns the connection.
struct Event {
    enum class Kind { Ready, StartFailed, ClaimDone, EnrollStatus, VerifyStatus } kind;
    bool ok = false;
    bool done = false;
    std::string status;
    std::uint32_t fid = 0;
    int templates = 0;
    GDBusMethodInvocation* invocation = nullptr;
};

void PostEvent(std::unique_ptr<Event> ev);   // defined with the D-Bus code

class Worker {
public:
    void Start() {
        // musl's default thread stack is 128 KiB; the session holds request
        // buffers on the stack. 8 MiB, as imsd does.
        pthread_attr_t attr;
        pthread_attr_init(&attr);
        pthread_attr_setstacksize(&attr, 8 * 1024 * 1024);
        pthread_create(&tid_, &attr, [](void* self) -> void* {
            static_cast<Worker*>(self)->Run();
            return nullptr;
        }, this);
        pthread_attr_destroy(&attr);
    }

    void Post(Job j) {
        std::lock_guard lk(mu_);
        jobs_.push_back(std::move(j));
        cv_.notify_one();
    }

    // Stops a running enrol/verify at its next frame. The op finishes on the
    // worker and reports OpFinished.
    void CancelOp() { cancel_.store(true); }

    void Quit() {
        {
            std::lock_guard lk(mu_);
            quit_ = true;
        }
        cancel_.store(true);
        cv_.notify_one();
        if (tid_) pthread_join(tid_, nullptr);
    }

    Session& TheSession() { return session_; }

private:
    void Run() {
        if (!session_.Start()) {
            PostEvent(std::make_unique<Event>(Event{ .kind = Event::Kind::StartFailed }));
            return;
        }
        PostEvent(std::make_unique<Event>(Event{ .kind = Event::Kind::Ready }));

        for (;;) {
            Job j;
            {
                std::unique_lock lk(mu_);
                cv_.wait(lk, [&] { return quit_ || !jobs_.empty(); });
                if (quit_) break;
                j = std::move(jobs_.front());
                jobs_.pop_front();
            }
            cancel_.store(false);
            switch (j.kind) {
            case Job::Kind::Claim: {
                int n = session_.SetActiveGroup(j.uid);
                auto ev = std::make_unique<Event>(Event{ .kind = Event::Kind::ClaimDone });
                ev->ok = n >= 0;
                ev->templates = n;
                ev->invocation = j.invocation;
                PostEvent(std::move(ev));
                break;
            }
            case Job::Kind::Enroll: {
                auto o = session_.Enrol(
                    j.uid, cancel_,
                    [&](int accepted, int total) {
                        (void)accepted; (void)total;
                        auto ev = std::make_unique<Event>(Event{ .kind = Event::Kind::EnrollStatus });
                        ev->status = "enroll-stage-passed";
                        PostEvent(std::move(ev));
                    },
                    [&] {
                        auto ev = std::make_unique<Event>(Event{ .kind = Event::Kind::EnrollStatus });
                        ev->status = "enroll-retry-scan";
                        PostEvent(std::move(ev));
                    },
                    /*maxFrames*/ 600);
                auto ev = std::make_unique<Event>(Event{ .kind = Event::Kind::EnrollStatus });
                ev->done = true;
                ev->ok = o.saved;
                ev->fid = o.fid;
                if (o.cancelled)       { ev->status = ""; ev->done = false; }
                else if (o.saved)      ev->status = "enroll-completed";
                else                   ev->status = "enroll-failed";
                if (!o.why.empty()) std::println("enrolment: {}", o.why);
                PostEvent(std::move(ev));
                break;
            }
            case Job::Kind::Verify: {
                auto o = session_.Verify(j.uid, cancel_, /*maxFrames*/ 600);
                std::println("verify: {} over {} press(es), {} frame(s)",
                             o.cancelled ? "cancelled" : !o.decided ? "undecided"
                             : o.matched ? "MATCH" : "NO MATCH", o.presses, o.frames);
                auto ev = std::make_unique<Event>(Event{ .kind = Event::Kind::VerifyStatus });
                ev->done = true;
                ev->fid = o.fid;
                if (o.cancelled)       { ev->status = ""; ev->done = false; }
                else if (!o.decided)   ev->status = "verify-unknown-error";
                else if (o.matched)    ev->status = "verify-match";
                else                   ev->status = "verify-no-match";
                PostEvent(std::move(ev));
                break;
            }
            }
        }
        session_.Stop();
    }

    Session session_;
    pthread_t tid_ = 0;
    std::mutex mu_;
    std::condition_variable cv_;
    std::deque<Job> jobs_;
    bool quit_ = false;
    std::atomic<bool> cancel_{false};
};

// =============================================================================
// net.reactivated.Fprint -- fprintd's interface, so pam_fprintd, the Plasma
// KCM and fprintd-enroll work against this daemon unmodified. MAIN THREAD.
// =============================================================================
constexpr const char* BusName = "net.reactivated.Fprint";
constexpr const char* ManagerPath = "/net/reactivated/Fprint/Manager";
constexpr const char* DevicePath = "/net/reactivated/Fprint/Device/0";
constexpr const char* ManagerIface = "net.reactivated.Fprint.Manager";
constexpr const char* DeviceIface = "net.reactivated.Fprint.Device";
constexpr const char* DeviceName = "FocalTech FT9391 (QTEE)";

constexpr const char* IntrospectionXml = R"xml(
<node>
  <interface name="net.reactivated.Fprint.Manager">
    <method name="GetDevices"><arg type="ao" name="devices" direction="out"/></method>
    <method name="GetDefaultDevice"><arg type="o" name="device" direction="out"/></method>
  </interface>
  <interface name="net.reactivated.Fprint.Device">
    <method name="ListEnrolledFingers">
      <arg type="s" name="username" direction="in"/>
      <arg type="as" name="enrolled_fingers" direction="out"/>
    </method>
    <method name="DeleteEnrolledFingers"><arg type="s" name="username" direction="in"/></method>
    <method name="DeleteEnrolledFingers2"/>
    <method name="DeleteEnrolledFinger"><arg type="s" name="finger_name" direction="in"/></method>
    <method name="Claim"><arg type="s" name="username" direction="in"/></method>
    <method name="Release"/>
    <method name="VerifyStart"><arg type="s" name="finger_name" direction="in"/></method>
    <method name="VerifyStop"/>
    <method name="EnrollStart"><arg type="s" name="finger_name" direction="in"/></method>
    <method name="EnrollStop"/>
    <signal name="VerifyFingerSelected"><arg type="s" name="finger_name"/></signal>
    <signal name="VerifyStatus"><arg type="s" name="result"/><arg type="b" name="done"/></signal>
    <signal name="EnrollStatus"><arg type="s" name="result"/><arg type="b" name="done"/></signal>
    <property name="name" type="s" access="read"/>
    <property name="num-enroll-stages" type="i" access="read"/>
    <property name="scan-type" type="s" access="read"/>
    <property name="finger-present" type="b" access="read"/>
    <property name="finger-needed" type="b" access="read"/>
  </interface>
</node>
)xml";

GDBusConnection* g_conn = nullptr;
GMainLoop* g_loop = nullptr;
Worker* g_worker = nullptr;
bool g_ready = false;

// Claim state. fprintd's model: one client holds the device at a time, on
// behalf of one user, and every operation is against that user's prints.
enum class Op { None, Enroll, Verify };
struct Claim {
    bool held = false;
    std::string sender;         // the bus name that holds it
    std::string user;
    std::uint32_t uid = 0;
    Op op = Op::None;
    std::string finger;         // for the op in progress
    fingerprintd::store::Map fingers;
};
Claim g_claim;
GDBusMethodInvocation* g_pendingClaim = nullptr;
guint g_claimWatch = 0;

void DropClaim(const char* why) {
    if (g_claimWatch) {
        g_dbus_connection_signal_unsubscribe(g_conn, g_claimWatch);
        g_claimWatch = 0;
    }
    if (g_claim.op != Op::None && g_worker) g_worker->CancelOp();
    if (g_claim.held)
        std::println("claim by {} for {} dropped: {}", g_claim.sender, g_claim.user, why);
    g_claim = {};
}

// A claim is held by a bus connection. If that connection goes away -- the
// client crashed, was killed, or simply never called Release -- the claim
// must go with it, or the device is wedged for everyone until the daemon
// restarts. fprintd watches the claimant's name for exactly this reason. Seen
// the hard way: a Claim from one busctl invocation, which exits immediately,
// left the device permanently "AlreadyInUse".
void WatchClaimant(const std::string& sender) {
    g_claimWatch = g_dbus_connection_signal_subscribe(
        g_conn, "org.freedesktop.DBus", "org.freedesktop.DBus", "NameOwnerChanged",
        "/org/freedesktop/DBus", sender.c_str(), G_DBUS_SIGNAL_FLAGS_NONE,
        [](GDBusConnection*, const gchar*, const gchar*, const gchar*, const gchar*,
           GVariant* params, gpointer) {
            const gchar* name = nullptr; const gchar* oldOwner = nullptr; const gchar* newOwner = nullptr;
            g_variant_get(params, "(&s&s&s)", &name, &oldOwner, &newOwner);
            if (g_claim.held && name && g_claim.sender == name && newOwner && *newOwner == '\0')
                DropClaim("client left the bus");
        },
        nullptr, nullptr);
}

std::string MapPath(std::uint32_t uid) {
    return fingerprintd::store::PathForUid(g_stateDir, uid);
}

fingerprintd::store::Map LoadMap(std::uint32_t uid) {
    std::string path = MapPath(uid);
    std::ifstream f(path);
    if (!f) {
        std::println("map {}: {}", path, ::strerror(errno));
        return {};
    }
    std::string text((std::istreambuf_iterator<char>(f)), std::istreambuf_iterator<char>());
    auto m = fingerprintd::store::Map::Decode(text);
    std::println("map {}: {} bytes, {} finger(s)", path, text.size(), m.Size());
    return m;
}

void SaveMap(std::uint32_t uid, const fingerprintd::store::Map& m) {
    std::error_code ec;
    std::filesystem::create_directories(g_stateDir, ec);
    std::string path = MapPath(uid);
    std::string tmp = path + ".tmp";
    {
        std::ofstream f(tmp, std::ios::trunc);
        f << m.Encode();
    }
    ::chmod(tmp.c_str(), 0600);
    std::filesystem::rename(tmp, path, ec);
}

void EmitDevice(const char* signal, GVariant* params) {
    if (!g_conn) return;
    g_dbus_connection_emit_signal(g_conn, nullptr, DevicePath, DeviceIface, signal, params, nullptr);
}

void ReturnError(GDBusMethodInvocation* inv, const char* name, const std::string& msg) {
    g_dbus_method_invocation_return_dbus_error(inv, std::format("net.reactivated.Fprint.Error.{}", name).c_str(), msg.c_str());
}

// Who is calling. Used for the one authorisation rule this daemon enforces.
std::optional<std::uint32_t> CallerUid(GDBusMethodInvocation* inv) {
    const gchar* sender = g_dbus_method_invocation_get_sender(inv);
    GError* err = nullptr;
    GVariant* r = g_dbus_connection_call_sync(
        g_conn, "org.freedesktop.DBus", "/org/freedesktop/DBus", "org.freedesktop.DBus",
        "GetConnectionUnixUser", g_variant_new("(s)", sender), G_VARIANT_TYPE("(u)"),
        G_DBUS_CALL_FLAGS_NONE, -1, nullptr, &err);
    if (!r) { if (err) g_error_free(err); return std::nullopt; }
    guint32 uid = 0;
    g_variant_get(r, "(u)", &uid);
    g_variant_unref(r);
    return uid;
}

std::optional<std::pair<std::string, std::uint32_t>> ResolveUser(const std::string& name,
                                                                 GDBusMethodInvocation* inv) {
    if (name.empty()) {
        // fprintd: an empty username means the caller.
        auto uid = CallerUid(inv);
        if (!uid) return std::nullopt;
        passwd* pw = ::getpwuid(*uid);
        return std::make_pair(pw ? std::string(pw->pw_name) : std::to_string(*uid), *uid);
    }
    passwd* pw = ::getpwnam(name.c_str());
    if (!pw) return std::nullopt;
    return std::make_pair(name, static_cast<std::uint32_t>(pw->pw_uid));
}

// The authorisation rule. fprintd uses polkit for this; polkit integration is
// not in this milestone, so the rule is the obvious conservative one: you may
// act on your own prints, and root may act on anyone's.
bool Authorised(GDBusMethodInvocation* inv, std::uint32_t targetUid) {
    auto caller = CallerUid(inv);
    return caller && (*caller == 0 || *caller == targetUid);
}

void PostEvent(std::unique_ptr<Event> ev) {
    g_idle_add([](gpointer data) -> gboolean {
        std::unique_ptr<Event> ev(static_cast<Event*>(data));
        switch (ev->kind) {
        case Event::Kind::Ready:
            g_ready = true;
            std::println("fingerprintd: ready");
            break;
        case Event::Kind::StartFailed:
            std::println(std::cerr, "fingerprintd: session bring-up failed -- exiting for systemd");
            g_main_loop_quit(g_loop);
            break;
        case Event::Kind::ClaimDone:
            if (ev->invocation) {
                if (ev->ok) {
                    std::println("claimed by {} for {} (uid {}, {} template(s) loaded)",
                                 g_claim.sender, g_claim.user, g_claim.uid, ev->templates);
                    g_dbus_method_invocation_return_value(ev->invocation, nullptr);
                } else {
                    DropClaim("group selection failed");
                    ReturnError(ev->invocation, "Internal", "could not select the user's group");
                }
                g_pendingClaim = nullptr;
            }
            break;
        case Event::Kind::EnrollStatus:
            if (!ev->status.empty())
                EmitDevice("EnrollStatus", g_variant_new("(sb)", ev->status.c_str(), ev->done ? TRUE : FALSE));
            if (ev->done && ev->ok) {
                auto f = fingerprintd::store::FingerFromName(g_claim.finger);
                if (f && ev->fid != 0) {
                    g_claim.fingers.Add(*f, ev->fid);
                    SaveMap(g_claim.uid, g_claim.fingers);
                    std::println("enrolled {} for uid {} as fid {}", g_claim.finger, g_claim.uid, ev->fid);
                } else {
                    std::println(std::cerr,
                                 "enrolled, but the trustlet reported no fid -- the finger cannot be "
                                 "named until it is seen in a verification");
                }
            }
            break;
        case Event::Kind::VerifyStatus:
            if (!ev->status.empty())
                EmitDevice("VerifyStatus", g_variant_new("(sb)", ev->status.c_str(), ev->done ? TRUE : FALSE));
            if (ev->done && ev->status == "verify-match")
                std::println("verified fid {} for uid {}", ev->fid, g_claim.uid);
            break;
        }
        return G_SOURCE_REMOVE;
    }, ev.release());
}

void HandleManager(GDBusMethodInvocation* inv, std::string_view method) {
    if (method == "GetDevices") {
        GVariantBuilder b;
        g_variant_builder_init(&b, G_VARIANT_TYPE("ao"));
        g_variant_builder_add(&b, "o", DevicePath);
        g_dbus_method_invocation_return_value(inv, g_variant_new("(ao)", &b));
        return;
    }
    if (method == "GetDefaultDevice") {
        g_dbus_method_invocation_return_value(inv, g_variant_new("(o)", DevicePath));
        return;
    }
    g_dbus_method_invocation_return_dbus_error(inv, "org.freedesktop.DBus.Error.UnknownMethod", "no such method");
}

void HandleDevice(GDBusMethodInvocation* inv, std::string_view method, GVariant* params) {
    namespace store = fingerprintd::store;
    const gchar* sender = g_dbus_method_invocation_get_sender(inv);

    if (!g_ready) {
        ReturnError(inv, "Internal", "device is still starting");
        return;
    }

    if (method == "Claim") {
        const gchar* username = nullptr;
        g_variant_get(params, "(&s)", &username);
        if (g_claim.held) {
            ReturnError(inv, g_claim.sender == sender ? "AlreadyInUse" : "AlreadyInUse",
                        "device is already claimed");
            return;
        }
        auto who = ResolveUser(username ? username : "", inv);
        if (!who) { ReturnError(inv, "Internal", "no such user"); return; }
        if (!Authorised(inv, who->second)) {
            ReturnError(inv, "PermissionDenied", "not allowed to act for that user");
            return;
        }
        g_claim = {};
        g_claim.held = true;
        g_claim.sender = sender;
        g_claim.user = who->first;
        g_claim.uid = who->second;
        g_claim.fingers = LoadMap(g_claim.uid);
        g_pendingClaim = inv;
        WatchClaimant(g_claim.sender);
        g_worker->Post(Job{ .kind = Job::Kind::Claim, .uid = g_claim.uid, .invocation = inv });
        return;
    }
    if (method == "Release") {
        if (!g_claim.held || g_claim.sender != sender) {
            ReturnError(inv, "ClaimDevice", "device is not claimed by you");
            return;
        }
        DropClaim("released");
        g_dbus_method_invocation_return_value(inv, nullptr);
        return;
    }
    if (method == "ListEnrolledFingers") {
        const gchar* username = nullptr;
        g_variant_get(params, "(&s)", &username);
        auto who = ResolveUser(username ? username : "", inv);
        if (!who) { ReturnError(inv, "Internal", "no such user"); return; }
        std::println("ListEnrolledFingers('{}') -> {} uid {}", username ? username : "",
                     who->first, who->second);
        auto m = LoadMap(who->second);
        if (m.Size() == 0) { ReturnError(inv, "NoEnrolledPrints", "no fingers enrolled"); return; }
        GVariantBuilder b;
        g_variant_builder_init(&b, G_VARIANT_TYPE("as"));
        for (const auto& e : m.Entries())
            g_variant_builder_add(&b, "s", std::string(store::NameOf(e.finger)).c_str());
        g_dbus_method_invocation_return_value(inv, g_variant_new("(as)", &b));
        return;
    }
    if (method == "DeleteEnrolledFingers" || method == "DeleteEnrolledFingers2"
        || method == "DeleteEnrolledFinger") {
        std::uint32_t uid = 0;
        std::optional<store::Finger> one;
        if (method == "DeleteEnrolledFingers") {
            const gchar* username = nullptr;
            g_variant_get(params, "(&s)", &username);
            auto who = ResolveUser(username ? username : "", inv);
            if (!who) { ReturnError(inv, "Internal", "no such user"); return; }
            if (!Authorised(inv, who->second)) { ReturnError(inv, "PermissionDenied", "not allowed"); return; }
            uid = who->second;
        } else {
            if (!g_claim.held || g_claim.sender != sender) {
                ReturnError(inv, "ClaimDevice", "device is not claimed by you");
                return;
            }
            uid = g_claim.uid;
            if (method == "DeleteEnrolledFinger") {
                const gchar* fname = nullptr;
                g_variant_get(params, "(&s)", &fname);
                one = store::FingerFromName(fname ? fname : "");
                if (!one) { ReturnError(inv, "InvalidFingername", "unknown finger"); return; }
            }
        }
        auto m = LoadMap(uid);
        if (one) m.Remove(*one); else m.Clear();
        SaveMap(uid, m);
        if (g_claim.held && g_claim.uid == uid) g_claim.fingers = m;
        // The trustlet-side template is NOT removed. FF_CMD_TA_REMOVE (0x2006)
        // exists but its payload has not been reverse-engineered, and guessing
        // at a command that writes to the store is how an index gets
        // invalidated. Until it is, a deleted finger loses its name and stops
        // being offered, but its template still occupies a slot in the group.
        std::println("deleted finger name(s) for uid {} -- trustlet template(s) NOT removed "
                     "(FF_CMD_TA_REMOVE not yet implemented)", uid);
        g_dbus_method_invocation_return_value(inv, nullptr);
        return;
    }
    if (method == "EnrollStart" || method == "VerifyStart") {
        if (!g_claim.held || g_claim.sender != sender) {
            ReturnError(inv, "ClaimDevice", "device is not claimed by you");
            return;
        }
        if (g_claim.op != Op::None) {
            ReturnError(inv, "AlreadyInUse", "an operation is already in progress");
            return;
        }
        const gchar* fname = nullptr;
        g_variant_get(params, "(&s)", &fname);
        std::string finger = fname ? fname : "";
        bool enroll = (method == "EnrollStart");
        if (enroll) {
            if (!store::FingerFromName(finger)) {
                ReturnError(inv, "InvalidFingername", "unknown finger");
                return;
            }
            if (g_claim.fingers.Full() && !g_claim.fingers.Has(*store::FingerFromName(finger))) {
                EmitDevice("EnrollStatus", g_variant_new("(sb)", "enroll-data-full", TRUE));
                g_dbus_method_invocation_return_value(inv, nullptr);
                return;
            }
        } else {
            if (finger != store::AnyFinger && !store::FingerFromName(finger)) {
                ReturnError(inv, "InvalidFingername", "unknown finger");
                return;
            }
            if (g_claim.fingers.Size() == 0) {
                ReturnError(inv, "NoEnrolledPrints", "no fingers enrolled for this user");
                return;
            }
        }
        g_claim.op = enroll ? Op::Enroll : Op::Verify;
        g_claim.finger = finger;
        g_dbus_method_invocation_return_value(inv, nullptr);
        if (!enroll) {
            // The trustlet identifies against every template in the group, so
            // the finger it will pick is whichever matches. Report what the
            // client asked for.
            std::string sel = finger == store::AnyFinger && g_claim.fingers.Size() > 0
                ? std::string(store::NameOf(g_claim.fingers.Entries().front().finger)) : finger;
            EmitDevice("VerifyFingerSelected", g_variant_new("(s)", sel.c_str()));
        }
        g_worker->Post(Job{ .kind = enroll ? Job::Kind::Enroll : Job::Kind::Verify,
                            .uid = g_claim.uid, .finger = finger });
        return;
    }
    if (method == "EnrollStop" || method == "VerifyStop") {
        if (!g_claim.held || g_claim.sender != sender) {
            ReturnError(inv, "ClaimDevice", "device is not claimed by you");
            return;
        }
        Op want = (method == "EnrollStop") ? Op::Enroll : Op::Verify;
        if (g_claim.op != want) {
            ReturnError(inv, "NoActionInProgress", "no such operation in progress");
            return;
        }
        // The operation is over when the CLIENT says so. A `done` status only
        // means no more status is coming; fprintd's clients call Stop after
        // it, and clearing the op ourselves on `done` made every one of them
        // fail with NoActionInProgress. Cancelling a loop that already ended
        // is harmless.
        g_worker->CancelOp();
        g_claim.op = Op::None;
        g_claim.finger.clear();
        g_dbus_method_invocation_return_value(inv, nullptr);
        return;
    }
    g_dbus_method_invocation_return_dbus_error(inv, "org.freedesktop.DBus.Error.UnknownMethod", "no such method");
}

void OnMethodCall(GDBusConnection*, const gchar*, const gchar* path, const gchar*,
                  const gchar* method, GVariant* params, GDBusMethodInvocation* inv, gpointer) {
    if (std::string_view(path) == ManagerPath) HandleManager(inv, method);
    else HandleDevice(inv, method, params);
}

GVariant* OnGetProperty(GDBusConnection*, const gchar*, const gchar*, const gchar*,
                        const gchar* prop, GError**, gpointer) {
    std::string_view p = prop;
    if (p == "name") return g_variant_new_string(DeviceName);
    if (p == "num-enroll-stages") return g_variant_new_int32(g_worker ? g_worker->TheSession().EnrolStages() : 10);
    if (p == "scan-type") return g_variant_new_string("press");
    if (p == "finger-present") return g_variant_new_boolean(g_worker && g_worker->TheSession().FingerPresent());
    if (p == "finger-needed") return g_variant_new_boolean(g_claim.op != Op::None);
    return nullptr;
}

const GDBusInterfaceVTable g_vtable = { OnMethodCall, OnGetProperty, nullptr, {} };

void OnBusAcquired(GDBusConnection* conn, const gchar*, gpointer) {
    g_conn = conn;
    GDBusNodeInfo* node = g_dbus_node_info_new_for_xml(IntrospectionXml, nullptr);
    g_dbus_connection_register_object(conn, ManagerPath, node->interfaces[0], &g_vtable, nullptr, nullptr, nullptr);
    g_dbus_connection_register_object(conn, DevicePath,  node->interfaces[1], &g_vtable, nullptr, nullptr, nullptr);
    g_dbus_node_info_unref(node);
    std::println("objects registered at {} and {}", ManagerPath, DevicePath);
}

gboolean OnTerm(gpointer) {
    std::println("fingerprintd: stopping");
    g_main_loop_quit(g_loop);
    return G_SOURCE_REMOVE;
}

int RunDaemon() {
    if (::geteuid() != 0) {
        std::println(std::cerr, "fingerprintd: must run as root (/dev/tee0, gpio, RPMB)");
        return 1;
    }
    Worker worker;
    g_worker = &worker;
    g_loop = g_main_loop_new(nullptr, FALSE);

    guint owner = g_bus_own_name(
        G_BUS_TYPE_SYSTEM, BusName, G_BUS_NAME_OWNER_FLAGS_NONE, OnBusAcquired,
        [](GDBusConnection*, const gchar* name, gpointer) { std::println("owning {}", name); },
        [](GDBusConnection*, const gchar* name, gpointer) {
            std::println(std::cerr, "lost {} -- is fprintd running? exiting", name);
            g_main_loop_quit(g_loop);
        },
        nullptr, nullptr);

    g_unix_signal_add(SIGTERM, OnTerm, nullptr);
    g_unix_signal_add(SIGINT, OnTerm, nullptr);

    // The session comes up on the worker; the bus answers "still starting"
    // until it posts Ready.
    worker.Start();
    std::println("fingerprintd {} starting on the system bus", Version);
    g_main_loop_run(g_loop);

    worker.Quit();
    g_bus_unown_name(owner);
    g_main_loop_unref(g_loop);
    return 0;
}

// -----------------------------------------------------------------------------
// Diagnostic modes: the probe flow, kept for a phone with no bus client at hand.
// -----------------------------------------------------------------------------
int RunProbe(bool doAuth, bool doEnrol, bool doCalSave, std::uint32_t gid, int frames) {
    namespace ta = fingerprintd::ta;
    Session s;
    if (!s.Start()) return 1;
    int n = s.SetActiveGroup(gid);
    (void)n;

    if (doCalSave) {
        if (g_sfsReadOnly) { std::println(std::cerr, "a calibration save writes; pass --sfs-writable"); return 1; }
        std::vector<std::byte> sd(0x10, std::byte{0});
        for (std::size_t k = 0; k < 4; k++)
            sd[k] = static_cast<std::byte>((ta::SaveMaskCalibration >> (8 * k)) & 0xFF);
        std::println("\n=== SAVE_DATA (calibration, no finger needed) ===");
        Report(ta::Cmd::SaveData, SendCommand(s.App(), ta::Cmd::SaveData, sd));
    }
    std::atomic<bool> cancel{false};
    if (doEnrol) {
        for (int c = 3; c > 0; c--) { std::println("*** press and LIFT, repeatedly, in {}... ***", c); std::this_thread::sleep_for(std::chrono::seconds(1)); }
        auto o = s.Enrol(gid, cancel,
            [](int a, int t) { std::println("  [{}/{}] accepted -- LIFT, then press again", a, t); },
            [] { std::println("  press rejected -- LIFT, shift the finger, press again"); },
            frames);
        std::println("enrol: completed={} saved={} fid={} {}", o.completed, o.saved, o.fid, o.why);
    }
    if (doAuth) {
        for (int c = 3; c > 0; c--) { std::println("*** press your finger in {}... ***", c); std::this_thread::sleep_for(std::chrono::seconds(1)); }
        auto o = s.Verify(gid, cancel, frames);
        std::println("verify: decided={} matched={} fid={}", o.decided, o.matched, o.fid);
    }
    s.Stop();
    return 0;
}

}  // namespace

int main(int argc, char** argv) {
    std::span<char*> args(argv, static_cast<std::size_t>(argc));
    bool probe = false, daemon = false, doAuth = false, doEnrol = false, doCalSave = false;
    std::uint32_t gid = 0;
    int frames = 120;
    for (std::string_view a : args.subspan(1)) {
        if (a == "--version") { std::println("fingerprintd {}", Version); return 0; }
        if (a == "--daemon") daemon = true;
        if (a == "--probe-tee") probe = true;
        if (a.starts_with("--ta=")) g_taPath = a.substr(5);
        if (a.starts_with("--config=")) g_cfgPath = a.substr(9);
        if (a == "--verbose") g_verbose = true;
        // Serving the store writable lets QTEE UNLINK a container it rejects,
        // which destroys an enrolled template. Opt in explicitly.
        if (a == "--sfs-writable") g_sfsReadOnly = false;
        if (a == "--rpmb-write") g_rpmbWrite = true;
        if (a == "--auth") { doAuth = true; probe = true; }
        if (a == "--enrol") { doEnrol = true; probe = true; }
        if (a == "--cal-save") { doCalSave = true; probe = true; g_verbose = true; }
        if (a.starts_with("--frames=")) frames = std::stoi(std::string(a.substr(9)));
        if (a.starts_with("--frame-gap=")) g_frameGapMs = std::stoi(std::string(a.substr(12)));
        if (a == "--undecided=nomatch") g_undecidedIsNoMatch = true;
        if (a.starts_with("--log-dir=")) g_logDir = a.substr(10);
        if (a.starts_with("--state-dir=")) g_stateDir = a.substr(12);
        if (a.starts_with("--rescan=")) g_rescan = std::stoi(std::string(a.substr(9)));
        if (a.starts_with("--group-path=")) g_groupPath = a.substr(13);
        if (a.starts_with("--samples=")) g_samples = std::stoi(std::string(a.substr(10)));
        if (a.starts_with("--sfs-root=")) g_sfsRoot = a.substr(11);
        if (a.starts_with("--gid=")) gid = static_cast<std::uint32_t>(std::stoul(std::string(a.substr(6))));
    }
    StartTranscript(g_logDir);
    if (daemon) return RunDaemon();
    if (probe) return RunProbe(doAuth, doEnrol, doCalSave, gid, frames);

    std::println(std::cerr,
                 "fingerprintd {}\n"
                 "  --daemon                       own net.reactivated.Fprint on the system bus\n"
                 "  --probe-tee [--gid=N]          bring the session up and report\n"
                 "  --auth | --enrol | --cal-save  diagnostic loops (see README)\n"
                 "  --sfs-root=DIR --sfs-writable --rpmb-write   storage policy",
                 Version);
    return 1;
}