Amado is designed around a narrow capability: a paired client may lock a Mac and read whether its current login session is locked. It does not expose unlock, login, shell execution, or general remote-control capabilities.

Amado reaches that capability in two ways: authenticated one-tap commands from your Apple devices, and local Bluetooth proximity auto-lock when you leave. Both paths can only lock.

Caffeinate is a separate local power-management capability. It does not add a network endpoint, but it can intentionally keep a MacBook running while its lid is closed.

• Pairing creates a random 256-bit secret on the Mac and transfers it through a QR code shown only after an explicit reveal action.
• The Mac stores that secret in Keychain. The iPhone stores paired-Mac data in its App Group container so the app, widget, Control Center control, and Watch relay can use it.
• Each Mac and iPhone installation has a stable UUID. Display names are never used as authentication or revocation identifiers. The Mac uses the iPhone UUID to show paired phones and reject normal requests from an installation removed in Settings. Scanning the QR code is the explicit path that restores a removed installation.
• Every command and response is authenticated with HMAC-SHA256. Command timestamps must be within 30 seconds, and a nonce may be accepted only once, limiting replay. A response carries the matching command nonce and its own freshness timestamp.
• Status responses contain the Mac's current locked or unlocked state plus its stable UUID, macOS-supplied name, and Bonjour service name so companion surfaces can keep their paired record current. Amado does not expose a session history or retain a remote activity log.
• LAN commands use Bonjour discovery and a direct TCP connection.
• Remote commands use HTTPS through a tunnel operated by the user. The local HTTP listener binds only to 127.0.0.1:51521.
• Proximity auto-lock runs on the Mac and observes the selected iPhone's Bluetooth signal. It does not expose another network command endpoint.
• Caffeinate uses a bundled LaunchDaemon that the user installs explicitly and an administrator approves through macOS Service Management. The root helper's XPC peer is restricted to Amado binaries signed by the same Developer ID team, and its protocol can only enable or disable pmset disablesleep; it cannot run caller-supplied commands. The override is held as an XPC lease, so an app disconnect or helper restart restores normal sleep.

TLS and HMAC solve different problems. The HTTPS tunnel protects traffic in transit and authenticates the public endpoint. HMAC authenticates commands and their matching responses even though the tunnel terminates TLS before forwarding them to the loopback listener.

Anyone with the pairing payload can lock the Mac. They cannot unlock it through Amado, but unexpected locks can still disrupt work. Do not publish the QR code, pairing string, Keychain contents, or a configuration backup that contains client pairing data.

Per-device removal is an application-level control around the stable client identifier. Because all phones paired from the same QR payload hold the same lock-only secret, regenerate the pairing secret if a device or pairing payload may be compromised. Regeneration is the cryptographic way to invalidate every copy of that credential.

Device UUIDs are identifiers, not secrets. Possessing a UUID does not authorize a command; the pairing secret and valid HMAC are still required.

The Stay awake and lock Caffeinate policy locks the session before requesting display sleep. Choosing Stay awake, keep unlocked is an explicit reduction in physical security: the Mac remains unlocked while it continues running. Amado requires one context-sensitive confirmation before applying this policy. When Auto-lock is enabled, its keep/pause choices appear as buttons in that same dialog. Anyone with physical access—or access through remote-control software already enabled on the Mac—may be able to use the session and access its apps, files, accounts, and data. Pausing proximity Auto-lock removes the additional lock that would otherwise occur when the selected iPhone leaves.

Caffeinate overrides the MacBook's normal lid-close sleep behavior; neither the locked policy nor a dark built-in display means the computer has stopped running. Closed-lid workloads can consume battery and generate heat. Use the Mac only on a hard, stable, well-ventilated surface, never in a bag, bedding, or another enclosed space, and follow Apple's operating-temperature and ventilation guidance.

The user is responsible for monitoring heat, battery level, workload, and physical access, and for disabling Caffeinate when conditions become unsafe. To the extent permitted by applicable law, Amado and its contributors are not liable for resulting battery depletion, interruption, data loss, hardware damage, overheating, or injury. See the warranty and liability limitations in sections 15 and 16 of the GNU Affero General Public License v3.0 only.

If a pairing secret may have leaked:

1. Open Settings › Pairing on the Mac.
2. Choose Regenerate pairing secret.
3. Pair the iPhone again.

Please avoid opening a public issue for a vulnerability that could put users at risk. Use GitHub's private vulnerability reporting for PangMo5/Amado when available.