[Vladush]

Description

This PR resolves screen unlock usability issues on KDE Plasma (supporting both Plasma 5 and Plasma 6 with pam_kwallet5.so / pam_kwallet6.so), and hardens the daemon, PAM module, CLI, and packaging against edge-case failures, hardware disconnects, blocking tasks, malformed configurations, and conffile conflicts.

Key Changes

1. KDE Plasma Screen Unlock & KWallet Integration

   • Automatically detects KDE lockscreen sessions (PAM_SERVICE == "kde") and inspects the PAM stack for pam_kwallet5.so or pam_kwallet6.so.
   • In auto / single_enter mode, injects an empty authtok (PAM_AUTHTOK = "") upon successful face authentication if unset. This prevents KWallet from double-prompting for a password while preserving password authentication fallback.
   • Documented rationale in ADR 0005.

2. Proximity Sensor Disconnect Fail-Safe

   • Hardened PresenceTripwire::poll_loop: explicitly invokes the presence callback with (false, 0) upon HID read errors or sensor disconnection.
   • Prevents stale presence state from leaving authentication gates unlocked after hardware disconnects at runtime.
   • Covered by unit test ReadErrorRevokesPreviouslyReportedPresence.

3. Strict Configuration Parsing & Fail-Closed Loading

   • Enforced strict syntax validation in config_parser.hpp: rejects unclosed section headers, unterminated quotes, and unexpected non-comment tokens.
   • Verified stream state (badbit) and rejected directory inputs as configuration paths.
   • Transactional configuration loading preserves existing state if parsing fails.
   • Corrected threshold documentation in config/config.ini and docs/man/linuxcampam.conf.5.md to reflect that higher threshold values are stricter (score >= threshold).
   • Unified whitespace trimming across provider and camera lists using split_trimmed.

4. Independent Lock Timer & Asynchronous Deadline Workers

   • Added PresenceActions: evaluates walk-away session locking on an independent thread timer decoupled from synchronous handle_client() request processing.
   • Added DeadlineWorker: guarantees cooperative cancellation and monotonic deadline bounds on blocking operations.
   • Hardened IPC protocol with monotonic clock deadlines using poll() and MSG_DONTWAIT / MSG_NOSIGNAL to eliminate Slowloris hangs.

5. Authentication Policy Permutation Coverage

   • Refined and verified STRICT_ALL, ADAPTIVE, and LENIENT_ANY policies in AuthEngine.
   • Added MultiCameraPolicyOutcomeMatrix test suite exercising 432 permutations across policies, mandatory camera flags, and outcomes (success, capture failure, darkness, face not found).

6. KDE Setup Script Reliability

   • In scripts/setup_config.sh, encapsulated immutable operations in a subshell with an EXIT trap registered before mktemp or attribute mutation. Guarantees chattr +i restoration under all exit paths including set -e.
   • Verified by automated regression tests in tests/test_setup_config.py.

7. Debian Packaging & Lifecycle Testing

   • Relocated explicit CPack conffile registration to packaging/cpack/conffiles outside of debhelper's discovered debian/ directory, resolving duplicate /etc/linuxcampam/config.ini registration warnings from dh_installdeb.
   • Added containerized lifecycle validation script (tests/debian_lifecycle_container.sh) covering install, upgrade, remove, and purge.

8. Code Deduplication & Architecture Refactoring

   • Extracted src/common/resources.hpp: unified RAII FileDescriptor and FileCloser.
   • Extracted src/common/socket_client.hpp: unified UNIX domain socket client connection with monotonic timeout.
   • Extracted src/common/user_lookup.hpp: unified safe dynamic buffer getpwnam_r username lookup.
   • Unified CLI cross-user privilege verification with may_access_user().
   • Unified legacy JSON embedding schema migration with embeddingArray().

9. C++ Core Guidelines & Bounds Safety

   • Replaced unchecked JSON and container operator[] indexing with bounds-safe .at(), .front(), and C++17 structured bindings.
   • Replaced magic numbers with named constants (kMaxBrightness, kMaxConfidence, kPrivateFileUmask, kDefaultCmdTimeoutMs, kLongCmdTimeoutMs).
   • Cleaned up unused headers (<array>, <charconv>).

Type of change

• Bug fix (non-breaking change which fixes an issue)
• Security / Hardening improvement
• Refactoring & deduplication
• Documentation update

How Has This Been Tested?

• SetupConfig test: tests/test_setup_config.py passing (trap registration and attribute rollback).
• Unit test suite (linuxcampam_tests): 161 tests passing (100%), including 432-permutation policy matrix, deadline workers, presence tripwire fail-safe, and independent lock timers.
• PAM integration tests (pam_integration_tests): 9 tests passing (100%), verifying KDE single-enter flow and KWallet authtok handling.
• Debian lifecycle checks: tests/test_debian_lifecycle.sh passing with clean conffiles metadata.
• Clang-tidy & static analysis: clean with zero warnings under WarningsAsErrors.

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have updated documentation and configuration examples
• My changes generate no new compiler or linter warnings
• All existing and new unit/integration tests pass cleanly