## Demo

![3rd Party Auth Demo](skills/3rd-party-auth/demo.webm)

2.5-minute narrated walkthrough of the Authentication Intent flow — from creating an intent to receiving a session token.

---

## Overview

Authentication 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.

### The Flow

1. **App creates an intent** — `POST /auth/intents` returns a token, confirmation code, and status URL
2. **App shows the code** — e.g. `BRTK-MXVZ` displayed in the terminal
3. **App opens browser** — points to `hydrogen.adom.inc/auth/intents/{token}`
4. **User logs in** — email/password or Google OAuth (new!)
5. **User enters the code** — types the confirmation code from their app
6. **Carbon creates a session** — Application-scoped, linked to the intent
7. **App receives the session token** — via SSE (real-time) or short polling

### Quick Start (JavaScript)

```javascript
// 1. Create the intent
const res = await fetch('https://carbon.adom.inc/auth/intents', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ max_age: 7776000 }),  // 90-day session
});
const intent = await res.json();

// 2. Show code + open browser
console.log(`Code: ${intent.confirmation_code}`);
open(`https://hydrogen.adom.inc/auth/intents/${intent.token}`);

// 3. Wait for authentication via SSE
const es = new EventSource(`${intent.updates_url}/status`);
es.addEventListener('authenticated', (e) => {
  const { session_token } = JSON.parse(e.data);
  // Use session_token for authenticated API calls
});
```

### Confirmation Code Format

- **8 uppercase consonants** formatted as `XXXX-XXXX`
- No vowels (avoids accidental profanity)
- Case-insensitive verification, dashes/spaces stripped
- Prevents phishing — user must see the code from the real app

### Intent Lifecycle

| State | Description |
|-------|-------------|
| Created | Waiting for user (15-min TTL) |
| Authenticated | User entered correct code, session linked |
| Consumed | App retrieved the session token |
| Expired | 15 minutes elapsed without completion |

### API Endpoints

| Method | Route | Description |
|--------|-------|-------------|
| `POST` | `/auth/intents` | Create a new intent (optional `max_age` body) |
| `GET` | `/auth/intents/{token}` | Retrieve intent details |
| `GET` | `/auth/intents/{token}/status` | Poll or SSE for auth status |
| `PATCH` | `/auth/intents/{token}` | Link user session (requires `confirmation_code`) |

### Google OAuth Sign-In

Users 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.

### Related

- **OAuth Gateway** — For integrating external OAuth providers (YouTube, GitHub, Slack) into Adom services. See the `oauth` skill for details.
- **Carbon API** — The backend that powers authentication intents, sessions, and user management.
- **Hydrogen** — The frontend that renders the login page, confirmation code entry, and Google OAuth flows.