El conector

Conectar un asistente

Todo es autoservicio: nadie en Orkasa registra la aplicación del corredor.

Qué pasa por debajo#

1. El cliente hace POST /api/mcp        → 401 + WWW-Authenticate:
                                           resource_metadata="…"
2. GET /.well-known/oauth-protected-resource     (RFC 9728)
                                        → authorization_servers: [orkasa.app]
3. GET /.well-known/oauth-authorization-server   (RFC 8414)
                                        → authorize / token / register
4. POST /api/oauth/register             (RFC 7591)  → client_id [+ secret]
5. GET  /oauth/authorize                → el corredor entra y aprueba
6. POST /api/oauth/token                → access + refresh
7. POST /api/mcp  (Bearer ork_at_…)     → tools/list, tools/call

Los pasos 2 a 4 son lo que convierte esto en autoservicio. Sin ellos habría que crear un cliente OAuth a mano para cada corredor — es decir, no habría conector.

El registro abierto es seguro#

POST /api/oauth/register no está autenticado. No puede estarlo: el cliente que se anuncia todavía no tiene ninguna identidad con nosotros.

Un registro no concede nada. Crea una identidad de aplicación sin agencia, sin token y sin datos detrás. Cada byte que llegue a leer algún día se decide después, por una persona conectada, en /oauth/authorize, dentro de su propio tenant. La superficie de abuso son filas en una tabla, no accesos — y los límites están cortados a esa medida:

• 10 registros por hora y por IP;
• redirect_uris en https, salvo loopback (RFC 8252 §7.3: una aplicación de escritorio recibe su código en http://127.0.0.1:<puerto>);
• permisos topados a los del conector, pida lo que pida el cliente;
• registrado dinámicamente implica PKCE obligatorio, como para cualquier cliente público.

El nombre lo elige un desconocido#

La pantalla de autorización dice « X quiere conectarse », y ese nombre lo eligió quien se registró. Por eso la pantalla enseña el destino real, no la URL que la aplicación declara:

Nombre elegido por la propia aplicación, sin verificar. Tus datos van a salir hacia evil.example. Autoriza solo si reconoces ese destino y tú iniciaste la conexión.

Enseñar el client_uri declarado como prueba de procedencia volvía el aviso en nuestra contra: bastaba registrarse con client_uri: "https://orkasa.app" para que la pantalla mostrara « · orkasa.app » debajo de un nombre inventado. La redirect_uri, en cambio, se verifica carácter a carácter contra la lista blanca del cliente — es lo único de esa pantalla que un suplantador no puede maquillar.

Y se puede retirar#

La tarjeta Conexiones, en los ajustes de Orkasa, lista los asistentes con acceso vivo, quién lo autorizó y cuándo, con un botón Desconectar. Sin eso, una autorización dada por error valía sesenta días — lo que dura el token de refresco.

Clientes de escritorio#

Un asistente de escritorio no tiene dónde esconder un secreto. Se registra con token_endpoint_auth_method: "none", obtiene un client_id solo, y lo que protege el intercambio es PKCE — en S256 y nada más.

Un code_challenge sin método se rechaza: el valor histórico por defecto en OAuth es plain, que compara el verificador con el reto en claro, y ese reto ya viajó dentro de la URL de autorización (o sea, por el historial del navegador y por los registros). Los metadatos solo anuncian S256, y el servidor ya no hace otra cosa.