fingerprintd/interfaces/Fingerprintd-Actions.cppm

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

// lint-disable-file fixed-width-types
/*
Fingerprintd:Actions — what a finger means, beyond "it was you".

The trustlet reports WHICH finger matched, and the daemon used to spend that
only on answering yes. Two things can now hang off it.

The first needs no configuration at all: every matched finger is announced on
the bus as net.catcrafts.Fingerprintd1.FingerMatched(finger, uid), always. That
is how a finger launches an application — an agent in the user's own session
hears it and decides what it means, from the user's own configuration. Root has
no session bus, no display and no business starting someone's applications, so
the daemon deliberately does not try; and since the signal is unconditional,
there is nothing to declare here to receive it.

What is left for this file is the two things that DO need the daemon:

    <finger>  [no-unlock]  [absolute command...]

    finger      an fprintd finger name, e.g. right-index-finger
    no-unlock   this finger never unlocks. The client is told the finger did
                not match, whatever really happened. The duress case.
    command     run by root when this finger matches.

At least one of the two must be present; a line with neither says nothing the
signal above does not already say, and is more likely a mistake than an
intention. '#' comments and blank lines are ignored, and a finger with no line
behaves exactly as it always did.

THIS FILE IS A ROOT-EXECUTION SURFACE. Anything that can write it gets root at
the next press of a finger. The parser refuses a file that is not owned by root
or that anyone else can write, and refuses it WHOLESALE rather than skipping
the offending line -- a half-applied security policy is worse than none.
Ownership is checked by the shell, which has the stat; this module states the
rule and holds the verdict.

WHAT no-unlock IS NOT. It is a panic button, not deniability. The rejection it
fabricates is far faster than a real one, this file names the finger in plain
text, and the finger still shows as enrolled. It reliably runs your script; it
does not reliably hide that it did.
*/

export module Fingerprintd:Actions;
import std;
import :Store;

export namespace fingerprintd::actions {

    struct Rule {
        store::Finger finger{};
        // False for a duress finger: it matches, and the client is told it did
        // not. Named for what the administrator wants rather than for the
        // fprintd status it produces.
        bool unlocks = true;
        std::string command;             // empty = announce only
    };

    // Why a file was rejected. Rejection is total: no rule from a file that
    // failed to parse is ever applied.
    enum class Error {
        None,
        NotWritableOnlyByRoot,   // the shell's stat says someone else can write it
        UnknownFinger,
        RelativeCommand,         // a command that is not an absolute path
        NothingToDo,             // neither no-unlock nor a command
        DuplicateFinger,         // two rules for one finger: ambiguous, not merged
    };

    inline constexpr std::string_view Describe(Error e) {
        switch (e) {
        case Error::None:                  return "ok";
        case Error::NotWritableOnlyByRoot: return "the file must be owned by root and writable by no one else";
        case Error::UnknownFinger:         return "not an fprintd finger name";
        case Error::RelativeCommand:       return "the command must be an absolute path";
        case Error::NothingToDo:           return "expected 'no-unlock', a command, or both";
        case Error::DuplicateFinger:       return "two rules for the same finger";
        }
        return "unknown";
    }

    struct Parsed {
        std::vector<Rule> rules;
        Error error = Error::None;
        int line = 0;                    // 1-based, 0 when the error is the file itself
        bool Ok() const { return error == Error::None; }
    };

    inline constexpr std::string_view NoUnlockKeyword = "no-unlock";

    inline std::string_view TrimBlanks(std::string_view v) {
        while (!v.empty() && (v.front() == ' ' || v.front() == '\t')) v.remove_prefix(1);
        while (!v.empty() && (v.back() == ' ' || v.back() == '\t')) v.remove_suffix(1);
        return v;
    }

    // `rootOnlyWritable` is the shell's answer about the file's mode and
    // owner. Passing false rejects the file without looking at a single rule:
    // a config root will execute is not worth parsing if someone else can
    // rewrite it between the parse and the press.
    inline Parsed Parse(std::string_view text, bool rootOnlyWritable) {
        Parsed p;
        // Every rejection discards the rules gathered so far. A file that
        // stops being valid halfway is not "valid up to there": applying the
        // prefix would leave a policy nobody wrote, and the missing half
        // could be the one that mattered.
        auto reject = [&p](Error e, int line) -> Parsed& {
            p.error = e;
            p.line = line;
            p.rules.clear();
            return p;
        };
        if (!rootOnlyWritable) return reject(Error::NotWritableOnlyByRoot, 0);

        int lineNo = 0;
        for (const auto part : std::views::split(text, '\n')) {
            lineNo++;
            std::string_view line(part.begin(), part.end());
            if (!line.empty() && line.back() == '\r') line.remove_suffix(1);
            line = TrimBlanks(line);
            if (line.empty() || line.front() == '#') continue;

            std::size_t sp = line.find_first_of(" \t");
            std::string_view name = line.substr(0, sp);
            std::string_view rest = sp == std::string_view::npos
                                  ? std::string_view{} : TrimBlanks(line.substr(sp));

            Rule r;
            auto fin = store::FingerFromName(std::string(name));
            if (!fin) return reject(Error::UnknownFinger, lineNo);
            r.finger = *fin;

            // The keyword is optional and, when present, leads.
            if (rest == NoUnlockKeyword) {
                r.unlocks = false;
                rest = {};
            } else if (rest.starts_with(NoUnlockKeyword)
                       && (rest[NoUnlockKeyword.size()] == ' '
                           || rest[NoUnlockKeyword.size()] == '\t')) {
                r.unlocks = false;
                rest = TrimBlanks(rest.substr(NoUnlockKeyword.size()));
            }
            r.command = std::string(rest);

            if (r.unlocks && r.command.empty()) return reject(Error::NothingToDo, lineNo);
            // An absolute path only. Resolving a bare name through PATH would
            // make what root executes depend on an environment this daemon
            // does not control.
            if (!r.command.empty() && !r.command.starts_with('/'))
                return reject(Error::RelativeCommand, lineNo);
            for (const Rule& e : p.rules) {
                if (e.finger == r.finger) return reject(Error::DuplicateFinger, lineNo);
            }
            p.rules.push_back(std::move(r));
        }
        return p;
    }

    inline const Rule* Find(const std::vector<Rule>& rules, store::Finger f) {
        for (const Rule& r : rules)
            if (r.finger == f) return &r;
        return nullptr;
    }
}