macOS MeshAgent: Complete Rebuild and Enhancement

Overview

This PR represents a comprehensive rebuild and enhancement of the macOS MeshAgent, implementing native macOS features, improving security, and providing a modern installation experience. The work includes KVM improvements, installation infrastructure, TCC permission handling, force agent updates with surgical plist management, and extensive documentation.

Summary

This PR transforms the macOS MeshAgent into a first-class macOS application with:

🖥️ Native macOS KVM architecture with LaunchD integration
🔐 Comprehensive TCC permissions system with real-time detection
📦 Professional Installation Assistant GUI for easy deployment
🏢 Multi-tenancy support via ServiceID system
🔄 Force agent updates with surgical plist preservation
📚 Extensive documentation (103+ module docs, command reference, architecture guides)
🛡️ Enhanced security with path validation and permission management

Total Changes: 233 files changed (+7,531 / -13,122 lines)

Commit Structure

This PR is organized into 7 chronological commit groups following the actual development timeline:

1. macOS: Implement KVM1 reversed socket architecture with LaunchD integration

Complete rewrite of macOS KVM (remote desktop) architecture
Reversed socket model: Agent creates socket, KVM connects through LaunchD
Eliminates security issues with traditional approach
Proper privilege separation and sandboxing support
Architecture: docs/macos-KVM-Architecture.md

2. macOS: Add ServiceID system for multiple installations

Reverse DNS-style service identification: meshagent[.serviceName][.companyName]
Enables multiple independent MeshAgent installations on same system
Support for multi-tenancy and service variants
Proper LaunchDaemon/LaunchAgent namespace separation
Documentation: docs/macOS-ServiceID-System.md

3. macOS: Unify -install and -upgrade commands with build infrastructure

Unified installation and upgrade logic for macOS
Professional logging infrastructure with timestamps
macOS application bundle support with proper Info.plist embedding
Build system improvements for universal binaries
Recursive directory creation for installation paths
Code-signing and notarization workflow integration

4. macOS: Add logger module and TCC permissions UI

New logger.js module with DEBUG/INFO/WARN/ERROR levels
Real-time TCC permission detection (Accessibility, Screen Recording, Full Disk Access)
Interactive permissions UI with visual status indicators
Pipe-based IPC for elevated permission checking
Preference-aware TCC checking (--disableTccCheck support)
Documentation: docs/macos-tcc-permissions.md

5. macOS: Add Installation Assistant UI and infrastructure improvements

Native Cocoa Installation Assistant with install/upgrade detection
Automatic .msh file discovery in app bundle and Downloads
Configuration viewer with value truncation
Admin credential prompting via Authorization Services
Installation path validation with security checks
Progress tracking and operation result display
Documentation: docs/macos-install-assistant.md

6. macOS: Final polish and stability improvements

Bug fixes:
- Fixed normalizeInstallPath() incorrectly stripping 'meshagent' from paths
- Fixed prepareFolders() to use recursive directory creation
- Fixed validate_installation_path() to handle non-existent parent directories
Complete command reference documentation
103+ comprehensive module documentation files
Updated README with full documentation index
macOS helper functions module (macOSHelpers.js)
Security permissions management module (security-permissions.js)

7. macOS: Force Updates and Surgical Plist Management

Force Agent Updates:

Server-triggered agent updates via MeshCentral -upgrade command
Surgical plist updates preserve user customizations during force updates
Atomic plist creation for fresh installations
Version tracking via meshagent_ver key in LaunchDaemon/LaunchAgent plists

Surgical Update Logic:

Cache existing plist customizations before cleanup
Cleanup always deletes old plists (prevents orphan accumulation)
Service-manager applies cached customizations to new plists
Preserves: StandardOutPath, StandardErrorPath, environment variables, custom arguments
Falls back to atomic replacement if meshagent_ver not present

Version Management:

Embedded version info exposed to JavaScript (require('MeshAgent').getVersion())
DRY-compliant: Single source of truth in C code
Build timestamp tracking
Version verification in build output

Argument Validation:

Master argument validation system for macOS
Whitelist-based approach (simple flags + prefix flags)
Prevents unknown/malicious arguments from reaching agent
Validates at earliest possible point (main.c)

Self-Update Infrastructure:

Enhanced logging for -upgrade command
Launchctl job cleanup at start of upgrade
Self-update debugging (macOS-specific logging to /tmp)
Success/failure tracking via UpdateInProgress flag

Build System Improvements:

Runtime universal binary detection
-buildver and -fullversion flags
Version verification in build output
MODULESYNC_MODE build variable (macos-only default)

Bug Fixes:

Install validation prevents blank .db creation
Improved Install UI version detection using binary
Fixed -fullinstall path construction
Fixed self-update service lookup for custom ServiceIDs
Installer logging verbosity control
AC power detection fix in pmset parsing

Key Features

🖥️ Remote Desktop (KVM)

Reversed Socket Architecture: Agent creates Unix domain socket, KVM connects via LaunchD
LaunchD Integration: Proper service lifecycle management
Security: Eliminates need for KVM to bind sockets as root
TCC Compliance: Integrates with macOS permission system

🔐 Security & Permissions

TCC Permissions UI: Real-time detection and visual indicators for required permissions
Path Validation: Installation paths validated against allowed locations
Permission Management: Automated file permission setting with security policies
Code Signing: Integrated workflow for signing and notarization

📦 Installation Experience

GUI Installation Assistant: Native Cocoa interface for install/upgrade
Auto-Discovery: Automatic .msh file detection
Multi-Tenancy: ServiceID system enables multiple installations
Recursive Path Creation: Supports complex installation paths
Progress Tracking: Real-time feedback during operations

🔄 Agent Updates & Plist Management

Force Updates: Server-triggered agent updates via MeshCentral
Surgical Plist Updates: Preserve user customizations during updates
Version Tracking: meshagent_ver key tracks installed version
Atomic vs Surgical: Intelligent update strategy based on plist state
Argument Validation: Whitelist-based security for macOS arguments
Self-Update Debugging: macOS-specific logging infrastructure

🏗️ Build Infrastructure

Universal Binaries: ARM64 + x86_64 support
App Bundle Creation: Proper .app bundle structure with Info.plist
Module Embedding: JavaScript modules embedded at build time
Code-Utils Integration: Build-time utilities for module processing

📚 Documentation

Command Reference: Complete CLI documentation (docs/meshagent-commands.md)
Module Documentation: 103+ modules comprehensively documented (docs/meshagent-modules/)
Architecture Guides:
- macOS KVM Architecture
- macOS TCC Permissions
- Installation Assistant
- ServiceID System
README: Updated with comprehensive documentation index (docs/README.md)

New Modules

`modules/logger.js`

Professional logging infrastructure with:

Log levels: DEBUG, INFO, WARN, ERROR
Timestamp formatting
Runtime log level configuration
Zero dependencies, cross-platform

`modules/macOSHelpers.js`

macOS platform helper functions:

Bundle detection and path resolution
ServiceID generation with reverse DNS conventions
LaunchDaemon/LaunchAgent management
Plist manipulation utilities

`modules/security-permissions.js`

Security permissions management:

File permission policies for 9 critical file types
Permission verification and enforcement
Secure file creation with race condition prevention
Installation integrity validation

Testing

Tested On

✅ macOS 26.x (Taho) - ARM64 & x86_64
✅ macOS 12.x (Monteray) - ARM64 & x86_64
✅ Universal binary functionality verified

Test Coverage

✅ Fresh installation with GUI
✅ Fresh installation via command-line
✅ Upgrade from existing installation
✅ Multiple installations with different ServiceIDs
✅ TCC permission detection and UI
✅ KVM functionality with LaunchD
✅ Installation path validation
✅ Recursive directory creation
✅ Bundle detection and operations
✅ Code signing and notarization workflow
✅ Force update from MeshCentral server
✅ Surgical plist update preserves customizations
✅ Atomic update for fresh installations
✅ Version tracking and verification
✅ Argument validation and security

Security Testing

✅ Path validation (injection prevention)
✅ Permission verification
✅ Race condition prevention in file creation
✅ Privilege escalation handling
✅ TCC compliance verification

Migration Guide

For Users Upgrading from Previous Versions

Installation:

Download new MeshAgent.app and .msh file (if new install)
Hold CMD key and double-click MeshAgent.app
Follow Installation Assistant (auto-detects upgrade)

Or via command-line:

sudo ./meshagent -install --installPath="/existing/path/"

ServiceID Migration:

Existing installations maintain compatibility
New installations use reverse DNS format
Multiple installations now supported via ServiceID

Force Updates:

Existing installations will receive surgical updates (customizations preserved)
Fresh installations use atomic plist creation
Version tracking helps detect update success/failure

For Developers

Build Requirements:

Xcode Command Line Tools
Code signing certificate (optional, for distribution)

Building:

make macos ARCHID=29  # Universal binary (ARM64 + x86_64)

Documentation:

See docs/README.md for complete documentation index
Module APIs: docs/meshagent-modules/
Command reference: docs/meshagent-commands.md

Compatibility

Maintains Compatibility With:

✅ MeshCentral server communication protocol
✅ Existing .msh configuration files
✅ Existing LaunchDaemon configurations
✅ Cross-platform module APIs

Platform Support:

macOS: Full support (primary focus of this PR)
Windows: Unaffected
Linux: Unaffected
BSD: Unaffected

Files Changed

New Files

docs/meshagent-commands.md - Complete command reference
docs/macos-KVM-Architecture.md - KVM architecture documentation
docs/macos-tcc-permissions.md - TCC permissions guide
docs/macos-install-assistant.md - Installation Assistant guide
docs/macOS-ServiceID-System.md - ServiceID system documentation
docs/meshagent-modules/ - 103+ module documentation files
modules/logger.js - Logging infrastructure
modules/macOSHelpers.js - macOS helper functions
modules/security-permissions.js - Permission management
meshcore/MacOS/Install_UI/ - Installation Assistant UI code
meshcore/MacOS/TCC_UI/ - TCC permissions UI code
meshcore/MacOS/bundle_detection.c - Bundle detection utilities
build/tools/code-utils/ - Build-time code utilities

Modified Files

modules/agent-installer.js - Fixed path normalization bugs, surgical plist caching and update logic
modules/service-manager.js - Added recursive directory creation, apply cached customizations, version tracking
meshcore/MacOS/Install_UI/mac_authorized_install.m - Fixed path validation
meshconsole/main.c - Argument validation, version exposure
meshcore/agentcore.c - Self-update debugging infrastructure
Makefile - macOS build improvements
Build scripts and configuration files

Reviewers' Guide

Key Areas for Review

Security 🛡️
- meshcore/MacOS/Install_UI/mac_authorized_install.m - Path validation
- modules/security-permissions.js - File permission policies
- meshconsole/main.c - Argument validation
- Installation path handling throughout
Architecture 🏗️
- docs/macos-KVM-Architecture.md - Review KVM design
- modules/macOSHelpers.js - ServiceID generation logic
- modules/agent-installer.js - Surgical plist update logic
- LaunchD integration points
User Experience 🎨
- meshcore/MacOS/Install_UI/ - Installation Assistant UI
- meshcore/MacOS/TCC_UI/ - Permissions UI
- Documentation clarity and completeness
Compatibility 🔄
- Cross-platform module changes
- Backward compatibility with existing installations
- MeshCentral server communication

Testing Recommendations

# 1. Test fresh installation with GUI
sudo MeshAgent.app/Contents/MacOS/meshagent --show-install-ui

# 2. Test upgrade
sudo ./meshagent -install

# 3. Test multiple installations
sudo ./meshagent -install --installPath="/opt/mesh1/" --serviceName="mesh1"
sudo ./meshagent -install --installPath="/opt/mesh2/" --serviceName="mesh2"

# 4. Verify KVM functionality
sudo /opt/mesh1/meshagent -kvm1

# 5. Check TCC permissions
# Double-click MeshAgent.app (not holding CMD)

# 6. Test force update from server
# Trigger -upgrade command from MeshCentral server

# 7. Verify surgical plist preservation
# Add custom StandardOutPath to plist, then force update

Related Issues

This PR addresses multiple long-standing issues and feature requests for macOS:

macOS KVM architecture improvements
Installation experience enhancement
TCC permission handling
Multi-tenancy support
Force agent updates with customization preservation
Documentation completeness

Related MeshCentral PR:

MeshCentral #7486 - Required for new -upgrade system

Acknowledgments

This work represents a comprehensive rebuild of macOS MeshAgent functionality, developed over several months with extensive testing and iteration.

Key Contributors:

Implementation: @PeetMcK
AI Assistance: Claude (Anthropic)

Checklist

[x] Self-review completed
[x] Documentation updated
[x] Manual testing completed
[x] Backward compatibility verified
[x] Security considerations addressed
[x] Commit history is clean and organized
[x] PR description is comprehensive

Questions?

For questions about this PR:

Review the comprehensive documentation in docs/
Check the commit messages for detailed change rationale
Refer to individual module documentation in docs/meshagent-modules/

Issues & Bug Reports

If you encounter any problems with this PR, please open an issue on my fork:

Repository: https://github.com/PeetMcK/MeshAgent
Branch: _100-PR-macOS-MeshAgent-Rebuild
Issues: https://github.com/PeetMcK/MeshAgent/issues

This helps track PR-specific feedback separately from the main repository.

Nov 27 '25 10:11 PeetMcK

@PeetMcK

Congratulations and thankyou for your hard work on this functionality. Its been great to watch and test this as the process moves along. I can't wait for this to get pushed through to main line, and I can start deploying the agent to all our Mac clients.

Nov 28 '25 01:11 llambkin

you accidently pushed ur tactial agent into the repo, please can u remove it

Dec 03 '25 12:12 si458

you accidently pushed ur tactial agent into the repo, please can u remove it

https://github.com/Ylianst/MeshAgent/compare/3b3b2408ea618fe37a4e5772991197df3f35fc76..cbc52b8e4e93d7b6569e0d51aaf26dcea6dab4f4

Cheers.Peet

Dec 04 '25 15:12 PeetMcK

https://github.com/Ylianst/MeshAgent/pull/313 and https://github.com/Ylianst/MeshCentral/pull/7486

Both updated and I'm calling it good. If anyone runs into issues testin feel free to open an issue:

https://github.com/PeetMcK/MeshAgent/issues/ and https://github.com/PeetMcK/MeshCentral/issues/

Dec 14 '25 10:12 PeetMcK