feat(skills): add garmin-auth skill with 2-turn Telegram MFA flow

2026-09-17 09:29:56 +02:00
parent 0162f9dcd3
commit 2dfce6967c
2 changed files with 603 additions and 0 deletions
@@ -0,0 +1,70 @@
+---
+name: garmin-auth
+description: Manage Garmin Connect authentication, proactive OAuth token keepalives, and interactive 2-turn MFA login over Telegram. Use when Garmin authentication fails (HTTP 401, expired tokens) or when the user asks to log into Garmin.
+---
+
+# 🔐 Garmin Connect Authentication & MFA Manager
+
+Headless authentication lifecycle manager for Garmin Connect, allowing OpenClaw to initiate logins, keep tokens perpetually fresh, and verify 6-digit MFA codes directly via Telegram.
+
+## 🎯 When to Use
+- **Authentication Errors**: Whenever a `garmin` MCP tool call fails with `Garmin authentication failed`, `Tokens expired`, `401 Unauthorized`, or `Failed to retrieve social profile`.
+- **User Request**: Whenever the user explicitly asks: *"Logge dich bei Garmin ein"*, *"Garmin MFA Code eingeben"*, *"Garmin Re-Auth"*, *"Verbinde Garmin"*.
+- **Keepalive / Watchdog**: During morning briefings or background checks to ensure tokens are proactively refreshed before expiring.
+- **Status Checks**: Whenever asked about Garmin token health or expiration: *"Ist Garmin eingeloggt?"*, *"Wie lange ist der Garmin-Token noch gültig?"*.
+
+---
+
+## 🕹️ Interactive Telegram MFA Login Flow (Protocol)
+
+Because Garmin requires Multi-Factor Authentication (OTP sent via SMS/email), login operates in **two conversation turns**:
+
+### Turn 1: Request Code (Initiate Login)
+1. Execute the `request-code` command:
+   ```bash
+   uv run /home/node/mop-skills/mop-skills/skills/garmin-auth/scripts/garmin_auth.py request-code
+   ```
+2. The command spawns a background authentication daemon and triggers Garmin to dispatch the 6-digit code to the user's email/SMS.
+3. Immediately send a clear, friendly prompt to the user on Telegram:
+   > 🔑 **Garmin-Authentifizierung erforderlich**
+   > Ich habe einen neuen Login bei Garmin gestartet. Garmin hat dir soeben einen 6-stelligen Sicherheitscode per SMS oder E-Mail gesendet.
+   > 
+   > Bitte antworte mir einfach kurz mit dem **6-stelligen Code**!
+
+### Turn 2: Verify Code (Complete Login)
+1. When the user sends a 6-digit message (e.g. `538291`, `538 291`):
+2. Execute the `verify` command:
+   ```bash
+   uv run /home/node/mop-skills/mop-skills/skills/garmin-auth/scripts/garmin_auth.py verify "<mfa_code>"
+   ```
+3. If successful:
+   - The tokens are automatically dumped to `/home/node/.openclaw/garmin_tokens/garmin_tokens.json` and base64 exported.
+   - Reply to the user:
+     > ✅ **Garmin-Login erfolgreich!**
+     > Angemeldet als **Moritz Graf**. Alle Garmin-Tools und Workouts sind wieder voll einsatzbereit.
+4. If the code was incorrect:
+   - The daemon remains alive for 5 minutes. Inform the user and allow them to retry:
+     > ⚠️ Der eingegebene Code war leider ungültig oder abgelaufen. Bitte prüfe den Code und sende ihn erneut.
+
+---
+
+## 🛠️ CLI Operations Reference
+
+### 1. Check Token Health & Validity
+```bash
+uv run /home/node/mop-skills/mop-skills/skills/garmin-auth/scripts/garmin_auth.py status
+```
+Outputs JSON with `valid`, `user`, `exp_utc`, `pending_mfa`.
+
+### 2. Proactive Keepalive (Refresh Token before Expiry)
+```bash
+uv run /home/node/mop-skills/mop-skills/skills/garmin-auth/scripts/garmin_auth.py keepalive
+```
+Touches the API, triggering `python-garminconnect`'s automatic token refresh and persisting the newly rotated refresh token to `/home/node/.openclaw/garmin_tokens/garmin_tokens.json`.
+
+---
+
+## 🔒 Security & Environment
+- Requires `GARMIN_EMAIL` and `GARMIN_PASSWORD` (already injected via `openclaw-secrets`).
+- Persistent storage: `/home/node/.openclaw/garmin_tokens/garmin_tokens.json` (on PVC `openclaw-data`).
+- Directory permissions are automatically set to `0700` and files to `0600`.