Third-Party Authentication

@@ -44,7 +44,6 @@   "source_path": "SKILL.md",   "readme": "## Demo\n\n![3rd Party Auth Demo](skills/3rd-party-auth/demo.webm)\n\n2.5-minute narrated walkthrough of the Authentication Intent flow — from creating an intent to receiving a session token.\n\n---\n\n## Overview\n\nAuthentication Intents let any application add \"Sign in with Adom\" functionality. The flow uses **confirmation codes** to prevent phishing — the user must verify that a code shown in their application matches what they see in the browser.\n\n### The Flow\n\n1. **App creates an intent** — `POST /auth/intents` returns a token, confirmation code, and status URL\n2. **App shows the code** — e.g. `BRTK-MXVZ` displayed in the terminal\n3. **App opens browser** — points to `hydrogen.adom.inc/auth/intents/{token}`\n4. **User logs in** — email/password or Google OAuth (new!)\n5. **User enters the code** — types the confirmation code from their app\n6. **Carbon creates a session** — Application-scoped, linked to the intent\n7. **App receives the session token** — via SSE (real-time) or short polling\n\n### Quick Start (JavaScript)\n\n```javascript\n// 1. Create the intent\nconst res = await fetch('https://carbon.adom.inc/auth/intents', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json' },\n  body: JSON.stringify({ max_age: 7776000 }),  // 90-day session\n});\nconst intent = await res.json();\n\n// 2. Show code + open browser\nconsole.log(`Code: ${intent.confirmation_code}`);\nopen(`https://hydrogen.adom.inc/auth/intents/${intent.token}`);\n\n// 3. Wait for authentication via SSE\nconst es = new EventSource(`${intent.updates_url}/status`);\nes.addEventListener('authenticated', (e) => {\n  const { session_token } = JSON.parse(e.data);\n  // Use session_token for authenticated API calls\n});\n```\n\n### Confirmation Code Format\n\n- **8 uppercase consonants** formatted as `XXXX-XXXX`\n- No vowels (avoids accidental profanity)\n- Case-insensitive verification, dashes/spaces stripped\n- Prevents phishing — user must see the code from the real app\n\n### Intent Lifecycle\n\n| State | Description |\n|-------|-------------|\n| Created | Waiting for user (15-min TTL) |\n| Authenticated | User entered correct code, session linked |\n| Consumed | App retrieved the session token |\n| Expired | 15 minutes elapsed without completion |\n\n### API Endpoints\n\n| Method | Route | Description |\n|--------|-------|-------------|\n| `POST` | `/auth/intents` | Create a new intent (optional `max_age` body) |\n| `GET` | `/auth/intents/{token}` | Retrieve intent details |\n| `GET` | `/auth/intents/{token}/status` | Poll or SSE for auth status |\n| `PATCH` | `/auth/intents/{token}` | Link user session (requires `confirmation_code`) |\n\n### Google OAuth Sign-In\n\nUsers can now sign in to Hydrogen with their Google account. This is built into the login page — 3rd party apps get it for free when users are directed to the Hydrogen login flow. New Google users are prompted to choose a username before their account is created.\n\n### Related\n\n- **OAuth Gateway** — For integrating external OAuth providers (YouTube, GitHub, Slack) into Adom services. See the `oauth` skill for details.\n- **Carbon API** — The backend that powers authentication intents, sessions, and user management.\n- **Hydrogen** — The frontend that renders the login page, confirmation code entry, and Google OAuth flows.\n",   "author": {-    "id": "695820315b5f1e4db2fcf602",     "name": "Kyle Bergstedt",     "email": "[email protected]"   },