feat: add parental controls (guardian) feature

[torlando-tech]

Summary

Adds a parental controls system ("guardian") that lets a parent lock a child's Columba device to only communicate with pre-approved contacts. This is an app-layer feature and does not modify the Reticulum protocol.

Key capabilities:

• Parent generates a QR code from Settings → Guardian → Show QR
• Child scans QR code to pair with guardian
• Guardian can send signed commands: LOCK/UNLOCK, ALLOW_ADD/REMOVE/SET, STATUS_REQUEST
• When locked: messages from non-allowed contacts are silently dropped at persistence and link layers
• When locked: identity switching, network config, and location sharing are disabled in UI

Security model:

• Commands are signed with guardian's Ed25519 identity key (RNS Identity)
• Signature verified on child device before any command is executed
• Replay attacks prevented via nonce + timestamp window (5 minutes)
• Guardian is always allowed to contact child even when locked
• Child cannot unpair while device is locked (prevents bypass)
• Active location sharing sessions stopped immediately on LOCK command

Anti-abuse design:

• Consent dialog explicitly states this is for parent/child use, not adult relationships
• Dialog explains factory reset as the escape route if misused
• Requires physical QR code scan to pair (cannot pair remotely)

What was fixed during rebase/review

This branch is a clean cherry-pick of the original PR #255 onto current main, with several security issues fixed:

1. Ed25519 signature verification was never called — GuardianCommandProcessor.processCommand() had a TODO. Now calls reticulumProtocol.verifyGuardianCommand().
2. Python guardian_verify_command parameter mismatch — original expected 6 hex-string args; binder sends (commandJson, signature_bytes, pubkey_bytes). Fixed to parse the JSON and reconstruct signed bytes correctly.
3. Location sharing not stopped on LOCK — executeLock() now injects LocationSharingManager and calls stopSharing(null).
4. Repository-layer unpair guard missing — GuardianRepository.removeGuardian() now returns Boolean and blocks when isLocked=true.
5. DB migration version collision — PR added migrations as 30→31/31→32 but main already uses those. Renumbered to 39→40/40→41, DB bumped to v41.
6. Stray conflict marker — ======= left in ReticulumServiceBinder.kt caused compile error. Removed.
7. return vs return false — bare return in ServicePersistenceManager.persistMessage() fixed.

Test plan

• Parent flow: Settings → Guardian → "Show My QR Code" generates scannable QR
• Child flow: Settings → Guardian → "Scan Guardian QR" pairs with parent
• LOCK command from parent disables "Network" and "My Contacts" tabs, shows lock banner
• LOCK command stops any active location sharing sessions
• ALLOW_ADD adds contact to allow list; messages from that contact pass through
• Messages from non-allowed contacts are silently dropped when locked
• Cannot unpair while locked (error message shown)
• Factory reset removes parental controls
• DB upgrade from v39 applies guardian tables migration cleanly

🤖 Generated with Claude Code

[github-actions]

❌ Threading Architecture Audit Failed

View Audit Report

Dispatcher Audit Report - Fri Feb 27 07:04:51 UTC 2026
========================================


═══════════════════════════════════════
1. Checking for runBlocking in Production Code
═══════════════════════════════════════
❌ VIOLATION: runBlocking found: app/src/main/java/com/lxmf/messenger/viewmodel/SettingsViewModel.kt:212:        private val initialGuardianConfig = kotlinx.coroutines.runBlocking {

═══════════════════════════════════════
2. Checking for Forbidden Patterns
═══════════════════════════════════════
✅ PASS: No GlobalScope usage found
✅ PASS: No Dispatchers.Unconfined usage found

═══════════════════════════════════════
3. Checking Python Initialization Uses Main.immediate
═══════════════════════════════════════
✅ PASS: Python initialization uses Dispatchers.Main.immediate

═══════════════════════════════════════
4. Summary - CI Optimized Check Complete
═══════════════════════════════════════
ℹ️  INFO: Sections 5-9 skipped for CI performance (non-critical checks)
ℹ️  INFO: All critical threading violations checked (runBlocking, GlobalScope, Unconfined, Python init)
ℹ️  INFO: For comprehensive analysis, run audit-dispatchers-full.sh locally

Please fix the dispatcher violations before merging.

[greptile-apps]

Greptile Summary

This PR adds a parental controls system that allows parents to lock and manage messaging on children's devices using cryptographically signed commands.

Key Changes

• Security implementation: Ed25519 signature verification for all guardian commands with anti-replay protection (nonce + timestamp validation)
• Database schema: Migrations 39→40 and 40→41 add three tables (guardian_config, allowed_contacts, paired_children)
• Message filtering: Multi-layer blocking at persistence, collector, and ViewModel levels when device is locked
• QR pairing: Physical QR code scan required to establish parent-child relationship (prevents remote pairing)
• UI restrictions: Lock state disables identity switching, network config, and location sharing in settings
• Location sharing: Active sessions stopped immediately when LOCK command is received

Security Fixes from Original PR #255

All seven security issues mentioned in the PR description have been properly addressed:

1. ✅ Signature verification now called in GuardianCommandProcessor.processCommand()
2. ✅ Python guardian_verify_command correctly parses JSON and reconstructs signed bytes
3. ✅ Location sharing stopped via LocationSharingManager.stopSharing() on LOCK
4. ✅ Repository removeGuardian() returns Boolean and blocks when locked
5. ✅ DB migrations renumbered to 39→40/40→41 to avoid collision
6. ✅ Conflict markers removed
7. ✅ return false used instead of bare return

Architecture

The implementation follows a clean layered architecture: Kotlin UI/ViewModels → Repository → Database layer, with Python bridge for cryptographic operations using RNS Identity. Commands flow through proper signature verification before any state changes.

Confidence Score: 4/5

• Safe to merge with one minor design consideration around timestamp-based replay protection
• Strong security implementation with Ed25519 signatures properly verified, multi-layer message filtering, and database migrations correctly numbered. The anti-replay protection at GuardianRepository.kt:305 rejects commands with timestamps ≤ last command timestamp, which could block rapid commands sent within the same millisecond - acceptable for this use case but worth noting as a deliberate trade-off favoring security over sub-millisecond command throughput
• Pay attention to GuardianRepository.kt (anti-replay logic) and GuardianCommandProcessor.kt (command execution flow)

Important Files Changed

Filename	Overview
app/src/main/java/com/lxmf/messenger/service/GuardianCommandProcessor.kt	Core command processing logic with proper Ed25519 signature verification, anti-replay checks, and location sharing termination on LOCK
python/guardian_crypto.py	Clean cryptographic primitives using RNS Identity for signing/verification with proper error handling
data/src/main/java/com/lxmf/messenger/data/repository/GuardianRepository.kt	Repository with lock state management, allow list operations, and replay protection; unpair correctly blocked when locked
app/src/main/java/com/lxmf/messenger/service/persistence/ServicePersistenceManager.kt	Persistence layer correctly filters messages from non-allowed contacts when device is locked
data/src/main/java/com/lxmf/messenger/data/di/DatabaseModule.kt	Database migrations 39→40 and 40→41 add guardian tables with proper indices and foreign keys
app/src/main/java/com/lxmf/messenger/reticulum/protocol/ServiceReticulumProtocol.kt	Bridge to Python layer for guardian operations with proper Base64 encoding of signatures and public keys
python/reticulum_wrapper.py	Guardian command sending/verification correctly reconstructs signed bytes from JSON for signature validation

Sequence Diagram

sequenceDiagram
    participant Parent as Parent Device
    participant Child as Child Device
    participant Python as Python Layer
    participant DB as Database

    Note over Parent,Child: QR Code Pairing Flow
    Parent->>Parent: Generate QR (dest hash + pubkey + signature)
    Child->>Parent: Scan QR code
    Child->>Python: Verify QR signature
    Python-->>Child: Valid
    Child->>DB: Store guardian config
    Child->>Parent: Send PAIR_ACK

    Note over Parent,Child: Lock Command Flow
    Parent->>Python: Sign LOCK command
    Python->>Python: Sign(cmd + nonce + timestamp + payload)
    Parent->>Child: Send LXMF message with command
    Child->>Child: Check sender = guardian
    Child->>Python: Verify signature
    Python->>Python: Reconstruct signed bytes
    Python->>Python: Verify Ed25519 signature
    Python-->>Child: Valid
    Child->>Child: Check nonce + timestamp
    Child->>DB: Set isLocked = true
    Child->>Python: Sync guardian config
    Child->>Child: Stop location sharing

    Note over Parent,Child: Message Filtering (Locked)
    Child->>Child: Receive message from non-allowed contact
    Child->>DB: Check isLocked + allow list
    DB-->>Child: Not allowed
    Child->>Child: Silently drop message

Loading

_{Last reviewed commit: 535c49b}

[greptile-apps]

_{38 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

The timestamp check rejects commands with timestamp <= lastCommandTimestamp, which means two commands sent in the same millisecond will cause the second to be rejected even with different nonces. For parental controls this is probably acceptable (commands shouldn't need sub-millisecond delivery), but consider if this could cause issues if a parent sends multiple rapid commands (e.g., LOCK followed immediately by ALLOW_ADD).

Prompt To Fix With AI

This is a comment left during a code review.
Path: data/src/main/java/com/lxmf/messenger/data/repository/GuardianRepository.kt
Line: 304-307

Comment:
The timestamp check rejects commands with `timestamp <= lastCommandTimestamp`, which means two commands sent in the same millisecond will cause the second to be rejected even with different nonces. For parental controls this is probably acceptable (commands shouldn't need sub-millisecond delivery), but consider if this could cause issues if a parent sends multiple rapid commands (e.g., LOCK followed immediately by ALLOW_ADD).

How can I resolve this? If you propose a fix, please make it concise.

[sentry]

Codecov Report

❌ Patch coverage is 81.85053% with 51 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
python/reticulum_wrapper.py	75.15%	39 Missing ⚠️
python/guardian_crypto.py	90.32%	12 Missing ⚠️

📢 Thoughts on this report? Let us know!

[torlando-tech]

unfortunately I am just hesitant about providing this as a dual child/parent role in columba. i think the design itself is sound but for one it is too easy for the child to bypass, and 2 it is too risky to apply controls maliciously if an attacker gains physical access to the device. if anything i think i will create a modified "kids mode" build or something of the app which excludes the more dangerous UI elements but uses the same cryptographic command scheme I've laid out in this PR