MacShield Documentation

Quick Start

MacShield is split into a native macOS menu bar app and an optional Chrome extension. Start with the app if you want to protect local macOS applications. Add the extension if you also want browser chat blur and website locks.

1. Download the latest release from GitHub.
2. Move MacShield to Applications and launch it.
3. Complete onboarding and create a backup password.
4. Grant Accessibility permission so MacShield can detect protected app activations.
5. Add one app to the protected list and confirm the overlay appears before content is visible.
6. Optional: enable Touch ID, Apple Watch proximity, idle lock, sleep lock, and browser privacy.

Installation

Download release

Use the signed release when available. Open the DMG, drag MacShield into Applications, then launch from Applications or Spotlight.

Download latest release

Build from source

git clone https://github.com/AryanVBW/MacShield.git
cd MacShield
open MacShield.xcodeproj

Build with Xcode 15 or newer on macOS 13 or newer. The app uses SwiftUI, AppKit, LocalAuthentication, CoreBluetooth, IOKit, ServiceManagement, Sparkle, and HotKey.

Requirements

macOS Setup

1. Create a backup password

The backup password is stored in the macOS Keychain and is used when biometric authentication is unavailable or disabled.

2. Grant Accessibility

Open System Settings, then Privacy and Security, then Accessibility. Enable MacShield. Without this permission, MacShield cannot reliably detect app launches and switches.

3. Choose protected apps

Use the app picker to add apps that should require authentication. Start small: test with a non-critical app before protecting messaging, finance, or developer tools.

4. Enable authentication methods

• Touch ID: handled by Apple's LocalAuthentication framework.
• Password: stored and verified through the macOS Keychain.
• Apple Watch: uses Bluetooth proximity signals and wrist detection where available.

5. Configure automation

Auto-lock on idle, lock on sleep, lock when Apple Watch leaves range, and auto-close inactive protected apps are optional. Enable only the behaviors that match your workflow.

Browser Extension

The Chrome extension adds two browser-focused protections: privacy blur for supported web apps and a website lock for custom domains.

Install unpacked extension

1. Open chrome://extensions/.
2. Enable Developer mode.
3. Select Load unpacked.
4. Choose BrowserExtensions/chrome-extension.
5. Pin MacShield from the Chrome toolbar.

Supported blur platforms

WhatsApp, Instagram, Telegram, Messenger, Discord, Slack, X/Twitter, LinkedIn, Gmail, Outlook, Teams, Facebook, Signal, and Element are covered by the extension's content script and CSS rules.

Website Lock

Set a master password, then add any domain such as github.com or notion.so. The lock guard runs at document_start and hides the page until password or biometric verification succeeds.

Storage model

• chrome.storage.local stores extension preferences, locked site configuration, password hash, password salt, and biometric credential references.
• chrome.storage.session stores unlocked hostnames for the current browser session and clears when Chrome closes.
• Message content is not read or stored. Blur is applied with CSS filters.

Permissions

Examples

Protect Messages and Mail

1. Add Messages and Mail in the protected app picker.
2. Enable Touch ID and password fallback.
3. Turn on lock on sleep and idle lock after 5 minutes.
4. Test by switching away, waiting, then returning to Messages.

Protect work browser tools

1. Install the extension.
2. Set a master password.
3. Add domains such as github.com, linear.app, or notion.so.
4. Enable auto-relock if you want a protected site to lock whenever you leave its tab.

Blur chat during screen sharing

1. Enable browser blur on Slack, Gmail, or WhatsApp Web.
2. Set blur intensity to Medium or Deep.
3. Use hover or selection reveal only when you are actively reading.

Architecture

MacShield uses a focused service architecture so app monitoring, authentication, overlays, updates, watch proximity, and browser controls can evolve independently.

MacShield/
  App/              App entry, AppDelegate, lifecycle wiring
  Core/
    Managers/       ProtectedAppsManager, SafetyManager
    Services/       App monitor, auth, overlays, blur, idle, sleep, watch, updates
    Storage/        UserDefaults wrapper, Keychain manager
  UI/               Menu bar, settings, onboarding, picker, overlay, components
  Models/           App settings, protected apps, blur config, lock sessions
BrowserExtensions/
  chrome-extension/ Manifest V3 extension with lock, blur, popup, auth pages
docs/               Static website, documentation, legal, support, status

The native app is distributed outside the Mac App Store because sandboxing would prevent reliable app activation interception and multi-monitor overlay behavior.

Reference

Important macOS services

Extension storage keys

Troubleshooting

Protected app does not lock

• Confirm MacShield is running in the menu bar.
• Re-enable Accessibility permission in System Settings.
• Remove and re-add the app from the protected list.
• Quit and relaunch the protected app to test launch detection.

Touch ID is unavailable

• Confirm Touch ID works in macOS System Settings.
• Use the backup password to unlock.
• Restart MacShield if the LocalAuthentication prompt does not appear.

Apple Watch unlock feels inconsistent

• Confirm Bluetooth is enabled and permission is granted.
• Wear the watch unlocked on your wrist.
• Adjust the RSSI threshold so unlock distance matches your desk setup.

Extension blur does not apply

• Reload the supported website after enabling blur.
• Confirm the site appears in the supported platform list.
• Disable other extensions temporarily to rule out CSS conflicts.
• Use Alt + X to confirm the content script is responding.

FAQ

Contributing

Open an issue before large changes. Small fixes, documentation improvements, selector updates for supported websites, and accessibility improvements are welcome.

• Keep changes scoped and explain the user-visible behavior.
• Do not weaken privacy guarantees or add analytics.
• Document any new permission, dependency, network request, or third-party service.
• Credit upstream projects and preserve license notices.

Open a GitHub issue

Changelog