For normal use, download the latest Developer ID-signed and notarized macOS DMG from GitHub Releases or the website download link. The official user-facing Mac package is the release DMG, not a development ZIP.
Open the DMG and install FacePass.
Launch FacePass from Applications or the installed app location.
Complete the in-app setup for Camera, Accessibility, Keychain password storage, Unlock Mode, and optional iPhone StandBy Unlock.
For development or local review, clone the repository and build FacePass yourself. Keep the same safety boundaries: no telemetry, no cloud sync, no persistent camera behavior, no ordinary password-field targeting, and no prompt auto-submit.
Requirements
macOS 13 or later
Xcode command line tools
Swift 5.9 or later
Clone
git clone https://github.com/Robert1124/FacePass.git
cd FacePass
Verify tools
xcode-select -p
swift --version
Verify, build, and test
Use verify-only mode when reviewing, build and launch locally when you are ready to run the app, and run the Swift test suite after changes.
./script/setup_and_run.sh --verify
./script/setup_and_run.sh
swift test
Visual Guide
These visuals show the current product surfaces and request flow. They are product visualizations, not Apple Face ID, Touch ID, or system authentication replacement screens.
1
Approve Locally
The iPhone uses local device authentication before sending a signed request.
2
Rediscover Nearby
The app tries the cached endpoint, Bonjour metadata, and bounded nearby-port recovery.
3
Verify on Mac
The Mac checks paired key, device IDs, timestamp, replay cache, counter, enabled state, and provider policy.
4
Act Narrowly
Locked sessions use the lock-screen typing path. Approved prompts receive value-only fill with no click, submit, or Return.
Permissions
Camera
Used for short local recognition windows. Sensitive lock-screen and approved prompt gates wait up to 10 seconds for the first accepted local match, may use short follow-up captures for the remaining required match before returning immediately, and stop capture after success, timeout, cancellation, or failure.
Accessibility
Used only for approved macOS authorization prompt value fill and the separate locked-session typing path.
Keychain
Password material is read through the PasswordVault boundary and must not be logged, displayed, or written elsewhere.
How to Use
1. Launch FacePass
Open the installed or locally built app. FacePass runs as a menu-bar helper with a full settings window for setup and status.
2. Grant only required permissions
Grant Camera for short local recognition windows and Accessibility for approved macOS prompt fill or the locked-session typing path. Sensitive recognition gates wait up to 10 seconds for the first accepted local match, may still require a short follow-up capture for the remaining match, and should not run without these explicit permissions.
3. Set up the Keychain password
Use the Password section to store the Mac login password through Keychain. The unlocked-session Verify Keychain Access action only checks access, discards the value immediately, and shows non-sensitive status.
4. Complete recognition setup
Use Recognition to enroll and verify local templates. Camera capture should stay short-lived, and raw photos or video frames should not be persisted.
5. Choose Unlock Mode routing
Unlock Mode can route approved flows through local recognition only, iPhone StandBy Unlock only, both providers, or local recognition for lock-screen unlock plus iPhone approval for approved prompt fill.
6. Enable the exact assist flow you need
For lock-screen assist, FacePass may type the Keychain password and press Return only after locked-session checks and the configured provider policy pass. For administrator/System Settings prompts, FacePass fills the password value only and never clicks OK, Continue, Modify Settings, Login, submit, or presses Return.
7. Enable launch at login in macOS if desired
Use macOS System Settings, Login Items, and add FacePass to Open at Login. This is a macOS-level startup choice, not a request to weaken Keychain, Accessibility, or privacy protections.
iPhone StandBy Unlock
The independent iPhone path relies on the user approving from a paired iPhone surface such as StandBy, Live Activity, Dynamic Island, AppIntent, or a static widget. The request is a signed local approval signal; the iPhone never receives the Mac password, Mac face data, or Mac camera frames.
Pairing and rediscovery use local HTTP with Bonjour metadata and QR-provided direct local endpoints when available. Endpoint scope is limited to /v1/status, /v1/pair, and /v1/standby-unlock.
When the Mac is locked and provider policy allows iPhone approval, a valid signed request can wake the display and use the same locked-session password typing path. When the Mac is unlocked and provider policy allows iPhone prompt fill, a valid request can fill only an approved administrator/System Settings password field without clicking or submitting.
Conditions apply only to automatic actions, not manual menu or hotkey actions. Missing or inconclusive required signals should fail closed.
Wi-Fi connected condition
External monitor condition
Power-state condition
Any/All match mode
Bluetooth is status-only and unavailable for now.
Security Notes
FacePass is an unlock and password-fill helper, not Apple Face ID, Touch ID, system biometrics, or a replacement for macOS authentication.
It has no analytics, telemetry, cloud sync, backend account service, APNs unlock path, WebSocket, third-party relay, or external unlock server. Local HTTP and Bonjour are used only for paired-device status, pairing, rediscovery, and signed StandBy Unlock requests.
Raw camera frames, photos, crops, sample buffers, and screenshots are not persisted. Recognition templates are local encrypted data with required metadata.
Distribution Boundaries
FacePass remains buildable from source. Developer ID distribution requires signing credentials, hardened runtime review, notarization, Sparkle appcast signing, and release packaging checks before users should rely on a downloaded macOS binary.
The macOS app is intended for Developer ID-signed and notarized DMG distribution with Sparkle 2 update checks at https://facepass.robertw.me/updates/appcast.xml. The website hosts the appcast under /updates, DMG release packages are hosted on GitHub Releases, and official user-facing DMGs should come from the tag-triggered GitHub Actions release workflow for v* tags or explicit workflow_dispatch runs.
Sparkle is only an appcast and package-download channel, not telemetry, a backend account service, cloud sync, or an unlock server. The iOS companion is distributed through its App Store listing and is not a workaround for Mac app distribution. Neither path changes the safety boundaries: no cloud account, no APNs unlock path, no telemetry, no upload of passwords, face data, raw frames, unlock state, or environment signals, and no Mac password transfer to iPhone.
Troubleshooting
Camera permission is missing
Open macOS privacy settings and grant Camera permission to FacePass. Restart the app if macOS does not refresh the permission state immediately.
Accessibility actions do not work
Confirm FacePass is enabled in Accessibility privacy settings. FacePass still only targets approved macOS authorization prompts and the lock-screen assist flow.
Authorization prompt was not filled
The prompt may be outside the approved allowlist, missing a strong prompt signal, or exposing multiple candidate fields. FacePass should fail closed in these cases.
FAQ
Is FacePass real Face ID for Mac?
No. FacePass is an app-level helper with a local recognition gate. It does not replace macOS authentication.
Can it fill website passwords?
No. Ordinary webpages and app password fields are intentionally unsupported.
Does it weaken Keychain prompts?
No. FacePass does not recommend Always Allow or weakening macOS Keychain protections.
Does the iPhone receive my Mac password?
No. The iPhone sends signed local requests only. Password material stays on the Mac and is read only through the Keychain-backed PasswordVault boundary.
