find-my-iphone: Alexa/REST bridge to ring iPhone via iCloud

apps/find-my-iphone/metadata/description.md

@@ -0,0 +1,23 @@
+# Find My iPhone Bridge
+
+Ring your iPhone by voice ("Alexa, open phone finder") or curl, self-hosted.
+
+## Endpoints
+
+| Route | Auth | Purpose |
+|-------|------|---------|
+| `POST /alexa` | Alexa signature + skill ID | Custom skill endpoint |
+| `GET /api/status` | X-Api-Key | Auth state: ready / mfa_required / error |
+| `POST /api/mfa` | X-Api-Key | One-time 2FA bootstrap `{"code":"123456"}` |
+| `GET /api/devices` | X-Api-Key | Device list with battery/status/location |
+| `POST /api/alert` | X-Api-Key | Ring a device `{"device":"name"}` (optional) |
+| `GET /api/location?device=` | X-Api-Key | Reverse-geocoded address |
+
+## First run (one time)
+
+1. Install with your Apple ID + password.
+2. `GET /api/status` shows `mfa_required`; a code push arrives on your Apple devices.
+3. `curl -X POST https://<domain>/api/mfa -H 'X-Api-Key: <key>' -H 'Content-Type: application/json' -d '{"code":"123456"}'`
+4. Trust token persists in the app volume - no more codes needed.
+
+Source: https://git.alexzaw.dev/alexz/find-my-iphone