# OAuth (referencia)

Para plataformas que publican en nombre de muchas empresas. Authorization code + PKCE **S256 obligatorio**. El access token (`ro_at_…`, 1 h) vale en `/api/v1` y `/api/mcp` igual que una clave.

## Registro
En https://remolom.com/developers/apps: nombre, web https, logo opcional y `redirect_uri` exactas (https, o `http://localhost`/`127.0.0.1` en desarrollo). Devuelve `client_id` (`ro_ci_…`) y `client_secret` (`ro_cs_…`, visible una vez). Con sesión: `PATCH /api/oauth/clients/:id` edita (nombre, web, logo, redirectUris) y `POST /api/oauth/clients/:id/rotate-secret` da un secreto nuevo (el anterior deja de valer al momento). La app nace pendiente: hasta su aprobación solo conecta empresas donde su dueño es owner o admin.

Scopes (separados por espacio): `events:read`, `events:write`, `tickets:read`, `webhooks:manage`.

## Flujo
1. Generar `code_verifier` (43–128 caracteres), `code_challenge = base64url(sha256(verifier))` y `state`; guardarlos en la sesión.
2. Redirigir a `https://remolom.com/api/oauth/authorize?response_type=code&client_id&redirect_uri&scope&state&code_challenge&code_challenge_method=S256`.
3. Vuelve a `redirect_uri?code=ro_ac_…&state` (o `?error=access_denied`). Comprobar `state`.
4. `POST https://remolom.com/api/oauth/token` (form o JSON): `grant_type=authorization_code&code&redirect_uri&code_verifier&client_id&client_secret` → `{ access_token, token_type: "Bearer", expires_in: 3600, refresh_token, scope }`. El código vale 60 s y un solo intento (reusarlo revoca el permiso emitido).
5. Renovar: `grant_type=refresh_token&refresh_token&client_id&client_secret`. **Rota**: guardar el refresh nuevo. Reusar uno viejo revoca el permiso entero; no renovar en paralelo.
6. Revocar: `POST /api/oauth/revoke token&client_id&client_secret` → 200 `{}`.

## Node
```js
import { createHash, randomBytes } from 'node:crypto'
const verifier = randomBytes(32).toString('base64url')
const challenge = createHash('sha256').update(verifier).digest('base64url')
const state = randomBytes(16).toString('base64url')
const url = 'https://remolom.com/api/oauth/authorize?' + new URLSearchParams({
  response_type: 'code', client_id: CLIENT_ID, redirect_uri: REDIRECT_URI,
  scope: 'events:read events:write', state, code_challenge: challenge, code_challenge_method: 'S256',
})
// callback:
const tokens = await fetch('https://remolom.com/api/oauth/token', {
  method: 'POST',
  body: new URLSearchParams({ grant_type: 'authorization_code', code, redirect_uri: REDIRECT_URI, code_verifier: verifier, client_id: CLIENT_ID, client_secret: CLIENT_SECRET }),
}).then((r) => r.json())
```

## Python
```python
import base64, hashlib, secrets, requests
verifier = secrets.token_urlsafe(32)
challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b"=").decode()
tokens = requests.post("https://remolom.com/api/oauth/token", data={
    "grant_type": "authorization_code", "code": code, "redirect_uri": REDIRECT_URI,
    "code_verifier": verifier, "client_id": CLIENT_ID, "client_secret": CLIENT_SECRET,
}).json()
```

## Errores
- 401 `invalid_client`: credenciales de la app.
- 400 `invalid_grant`: código caducado/usado, `redirect_uri` distinta, verifier que no casa o refresh reusado.
- Con el token: 401 si se revocó o la app se suspendió; 403 si falta el scope.
