@pharmadate/mcp 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,184 @@
-# Temporary Holding Version
+# @pharmadate/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Servidor [MCP](https://modelcontextprotocol.io) de Pharmadate. Permite a un asistente de IA (Claude, ChatGPT, Cursor, VS Code...)
+consultar el catálogo, valorar y cursar pedidos y, si eres partner (TopFarma...), gestionar tus farmacias, **sobre la API v1 de
+Pharmadate** (`/api-docs`). No accede a la base de datos: toda la autorización la hace la API.
+
+> **Estado (fase 1):** partners y farmacias. Las herramientas de administración interna llegan en la fase 2.
+> El paquete está en npm (`npx -y @pharmadate/mcp`) y el servidor remoto está activo en producción.
+
+- Paquete npm: `@pharmadate/mcp` · Registro MCP: `es.pharmadatepedido/mcp`
+- Remoto (Streamable HTTP): `https://www.pharmadatepedido.es/mcp`
+- 19 herramientas; el **nombre de cada una es el `operationId`** del OpenAPI (`frontend/api-docs/openapi.yaml`).
+
+## Qué puede hacer cada credencial
+
+| Credencial | Prefijo | Herramientas |
+|---|---|---|
+| **Partner** | `pk_partner_...` | Las 19: las operativas (con el argumento `pharmacy`) y la gestión de sus farmacias |
+| **Farmacia** | `pk_live_...` | 12: las operativas, sobre su propia farmacia (sin argumento `pharmacy`) |
+
+### Operativas (12) — farmacia, o partner con `pharmacy`
+
+| Herramienta | Tipo | Para qué |
+|---|---|---|
+| `ping` | lectura | Comprobar la credencial y ver quién eres |
+| `getCatalog` | lectura | Buscar en el catálogo (`q` por nombre o laboratorio; 50 por página) |
+| `getConditions` | lectura | Condiciones de un código nacional |
+| `lookupConditions` | lectura | Condiciones de hasta 1000 códigos |
+| `createQuote` | lectura | Valorar una cesta (no crea nada). **Siempre antes de pedir** |
+| `createOrder` | escritura, idempotente | Pedido **REAL**. `external_ref` obligatoria |
+| `listOrders`, `getOrder`, `getOrderModification` | lectura | Seguimiento de pedidos, faltas y modificaciones |
+| `listOrderShipments`, `getOrderShipment`, `getShipment` | lectura | Envíos |
+
+### Solo partner (7)
+
+| Herramienta | Tipo | Para qué |
+|---|---|---|
+| `listPharmacies`, `getPharmacy` | lectura | Tus farmacias (nunca devuelven la API key completa) |
+| `createPharmacy` | escritura | Alta |
+| `updatePharmacy` | escritura (destructiva) | Modificar datos |
+| `deactivatePharmacy` | destructiva, idempotente | Baja lógica (se deshace con `reactivatePharmacy`) |
+| `reactivatePharmacy` | escritura | Deshacer una baja (API key nueva) |
+| `rotatePharmacyApiKey` | destructiva | Key nueva; **invalida la anterior en el acto** |
+
+Cada herramienta lleva las *annotations* MCP (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) para que el cliente
+pida confirmación en las que escriben. Además hay 4 *resources* (`pharmadate://docs/integration-guide`, `.../errors`, `.../openapi`,
+`pharmadate://me`), 4 *prompts* (`placeOrder`, `orderStatus` y, para partners, `onboardPharmacy` y `recoverPharmacyAccess`) y
+unas *instrucciones del servidor* con las reglas de uso.
+
+## Conectarlo
+
+### Claude Code (remoto)
+
+```bash
+claude mcp add --transport http pharmadate https://www.pharmadatepedido.es/mcp \
+  --header "Authorization: Bearer pk_partner_XXXXXXXX"
+```
+
+Sin `--header`, Claude Code arranca el login OAuth en el navegador (`/mcp` dentro de Claude Code).
+
+### Claude Code / Claude Desktop (local, stdio)
+
+```bash
+claude mcp add pharmadate --env PHARMADATE_API_KEY=pk_partner_XXXXXXXX --env PHARMADATE_MCP_MODE=STANDARD -- npx -y @pharmadate/mcp
+```
+
+Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "pharmadate": {
+      "command": "npx",
+      "args": ["-y", "@pharmadate/mcp"],
+      "env": {
+        "PHARMADATE_API_KEY": "pk_partner_XXXXXXXX",
+        "PHARMADATE_MCP_MODE": "STANDARD"
+      }
+    }
+  }
+}
+```
+
+### Cursor / VS Code
+
+Cursor (`~/.cursor/mcp.json`) o VS Code (`.vscode/mcp.json`, clave `servers`):
+
+```json
+{
+  "mcpServers": {
+    "pharmadate": {
+      "url": "https://www.pharmadatepedido.es/mcp",
+      "headers": { "Authorization": "Bearer pk_partner_XXXXXXXX" }
+    }
+  }
+}
+```
+
+### Claude.ai y ChatGPT (OAuth)
+
+*Ajustes > Conectores > Añadir conector personalizado* y la URL `https://www.pharmadatepedido.es/mcp`. El cliente abre una página de
+Pharmadate donde **pegas tu API key**; no hace falta configurar ningún cliente OAuth (el registro es dinámico).
+
+> **Consejo para partners:** crea una credencial dedicada «MCP» en `/partner.html` (`POST /api/partner/tokens`). Así la puedes revocar
+> sin tocar tu integración.
+
+## Variables de entorno (stdio)
+
+| Variable | Obligatoria | Descripción |
+|---|---|---|
+| `PHARMADATE_API_KEY` | sí | Key de partner o de farmacia |
+| `PHARMADATE_MCP_MODE` | no | `READ_ONLY` (**por defecto**: solo lectura y valoración) o `STANDARD` (pedidos y gestión de farmacias) |
+| `PHARMADATE_PHARMACY_REF` | no | Solo partners: CIF de la farmacia por defecto (se verifica antes de usarla) |
+| `PHARMADATE_API_URL` | no | Por defecto `https://www.pharmadatepedido.es/api` (la beta: `.../api` de su URL) |
+
+El servidor remoto trabaja siempre en modo `STANDARD` (cada cliente pide confirmación por las *annotations*); el operador puede dejarlo
+en `READ_ONLY` con `MCP_REMOTE_MODE`.
+
+## Seguridad
+
+- **La farmacia se resuelve antes de operar (punto crítico).** Con una key de partner, la API da de alta *automáticamente* la farmacia de
+  un CIF desconocido en cualquier ruta operativa. Por eso el MCP, con `pharmacy: { pharmacy_id }` (preferido) o `{ cif }`, la busca antes
+  entre las **tuyas** y activas; si no aparece (o es de otro partner, o está de baja) responde «farmacia no encontrada entre las tuyas» y
+  **no llama a la API operativa**. Solo entonces envía `X-Pharmacy-Ref`, y **nunca** `pharmacy` ni `pharmacy_ref` en el cuerpo.
+- **Sin estado de negocio:** cada llamada se autoriza en la API. Un partner nunca ve las farmacias de otro.
+- **Keys:** nunca van a logs ni a mensajes de error (se redactan por patrón). `createPharmacy`, `reactivatePharmacy` y `rotatePharmacyApiKey` solo
+  muestran el prefijo; con `reveal_api_key: true` la key completa va en un bloque aparte con `annotations.audience: ["user"]`. **Puede quedar en el
+  historial del chat**: úsalo cuando la necesites de verdad. Si no la revelas al reactivar o rotar, esa key no se muestra en ningún sitio.
+- **Límites del MCP** (por credencial, en memoria del proceso): 30 escrituras/hora, 10 `createOrder`/hora y 500 líneas por quote o pedido; en los
+  endpoints sin autenticar, 30 peticiones/minuto por IP. La API añade sus 120 peticiones/minuto.
+- **Pedidos:** `createOrder` es real, firme e **idempotente por `external_ref`** (obligatoria): reintentar con la misma ref y la misma cesta no duplica.
+  Si se corta la llamada, el modelo debe reintentar con la **misma** ref.
+- **Auditoría:** cada llamada queda en `api_audit` con `User-Agent: pharmadate-mcp/<versión> (remote|stdio; client=<nombre>)` y la IP real.
+
+### OAuth 2.1 sin base de datos
+
+`/.well-known/oauth-authorization-server`, `/register` (DCR), `/authorize`, `/token` y `/.well-known/oauth-protected-resource/mcp`, en la raíz.
+El `code` (60 s), el access token (1 h) y el refresh token (30 días, tope de 90 días de sesión) son **la API key cifrada con AES-256-GCM** con
+`MCP_OAUTH_SECRET` (más PKCE, cliente y caducidad); el `client_id` es la metadata del registro firmada con HMAC. **Revocar es rotar o revocar la key**:
+cada llamada se valida contra la API y un refresh con la key revocada se rechaza. Cambiar `MCP_OAUTH_SECRET` cierra todas las sesiones.
+
+## Despliegue (operador)
+
+El MCP vive en `mcp/` y se monta **dentro de la app de Elastic Beanstalk**, detrás de `MCP_ENABLED=1`. Sin esa variable no se carga ni se expone nada.
+
+| Variable (EB) | Descripción |
+|---|---|
+| `MCP_ENABLED=1` | Activa `POST /mcp` y las rutas OAuth |
+| `MCP_PUBLIC_URL` | URL pública, p. ej. `https://www.pharmadatepedido.es` (issuer y recurso) |
+| `MCP_OAUTH_SECRET` | 32+ caracteres aleatorios (`openssl rand -base64 48`) |
+| `MCP_ALLOWED_ORIGINS` | Opcional: orígenes de navegador extra (por defecto claude.ai, claude.com, chatgpt.com) |
+| `MCP_ALLOWED_HOSTS` | Opcional: hostnames extra para la cabecera `Host` (protección contra DNS rebinding) |
+| `MCP_REMOTE_MODE` | Opcional: `READ_ONLY` para un remoto de solo lectura |
+| `MCP_PROXY_HOPS` | Opcional: proxies de confianza delante de la app para leer `X-Forwarded-For` (**2** con ALB + nginx, por defecto; **1** en la beta) |
+
+Los workflows `deploy-prod.yml`, `deploy-dev.yml` y `deploy-beta.yml` compilan el MCP (`cd mcp && npm ci && npm run build`) y meten `mcp/dist` en el zip; las
+dependencias (`@modelcontextprotocol/sdk`, `zod`, `pino`) están en `backend/package.json` porque EB solo instala las de producción. **La beta solo sirve HTTP**
+(sin certificado): el OAuth exige HTTPS salvo en `localhost`, así que allí se activa además `MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL=true` (**nunca en producción**).
+
+### Publicar (requiere aprobación)
+
+1. `mcp/package.json` y `mcp/server.json` con la misma versión; tag `mcp-vX.Y.Z` → `.github/workflows/mcp-publish.yml` (npm con procedencia + registro MCP).
+2. Secrets: `NPM_TOKEN` y `MCP_REGISTRY_DNS_PRIVATE_KEY`.
+3. Namespace `es.pharmadatepedido/*` del registro: verificación por DNS. Genera un par Ed25519 (`openssl genpkey -algorithm Ed25519`), publica en GoDaddy el TXT
+   `pharmadatepedido.es  TXT  "v=MCPv1; k=ed25519; p=<clave pública base64>"` y guarda la privada (hex) en el secret. Detalles: documentación de `mcp-publisher`.
+
+## Desarrollo
+
+```bash
+cd mcp && npm ci
+npm test                    # unitarios: contrato con el OpenAPI, snapshots por rol, resolución de la farmacia, aislamiento, OAuth, límites
+npm run build
+npm run test:integration    # backend real (SQLite de pruebas, requiere `cd backend && npm ci`) con MCP_ENABLED=1: HTTP, OAuth y stdio
+npm run dev                 # stdio con tsx (PHARMADATE_API_KEY=...)
+MCP_OAUTH_SECRET=$(openssl rand -hex 32) npm run dev -- --transport=http   # HTTP local en :3333
+```
+
+Probar con el inspector: `npx @modelcontextprotocol/inspector` y la URL `http://localhost:3333/mcp` (Streamable HTTP, cabecera `Authorization: Bearer <key>`).
+
+Diseño completo y decisiones: [`docs/diseno_mcp.md`](../docs/diseno_mcp.md).
+
+## Desarrollado por
+
+Desarrollado por [Nubiia](https://nubiia.es) · Contacto: samuel.fraga@nubiia.es

package/dist/auth/crypto.d.ts

@@ -0,0 +1,16 @@
+export type TokenKind = 'code' | 'access' | 'refresh';
+export declare const MIN_SECRET_LENGTH = 32;
+export interface DerivedKeys {
+    enc: Buffer;
+    mac: Buffer;
+}
+export declare function deriveKeys(secret: string): DerivedKeys;
+/** Cifra un objeto JSON en un token opaco con el prefijo de su tipo. */
+export declare function seal(kind: TokenKind, payload: object, keys: DerivedKeys): string;
+/** Descifra y verifica. Devuelve `null` si el token esta manipulado, es de otro tipo o no es nuestro. */
+export declare function open<T extends object>(kind: TokenKind, token: string, keys: DerivedKeys): T | null;
+/** Si el texto parece un token del OAuth del MCP (de cualquier tipo). */
+export declare function looksLikeMcpToken(token: string): boolean;
+/** Firma un objeto: `base64url(json).base64url(hmac)`. Es el `client_id` del registro dinamico. */
+export declare function sign(payload: object, keys: DerivedKeys): string;
+export declare function verify<T extends object>(signed: string, keys: DerivedKeys): T | null;

package/dist/auth/crypto.js

@@ -0,0 +1,83 @@
+/**
+ * Cifrado y firma sin estado del OAuth del MCP.
+ *
+ * No hay base de datos: todo lo que el servidor necesita recordar viaja DENTRO del propio token, cifrado con
+ * AES-256-GCM (confidencialidad + integridad) con claves derivadas de `MCP_OAUTH_SECRET` por HKDF.
+ *
+ *   - code           (60 s)   API key + PKCE + client + redirect_uri
+ *   - access token   (1 h)    API key + client + scopes + resource
+ *   - refresh token  (30 d)   API key + client + scopes + inicio de la cadena (tope 90 d)
+ *   - client_id (DCR)         metadata del registro firmada con HMAC-SHA256
+ *
+ * Cada tipo usa un AAD distinto: un code no se puede presentar como access token ni al reves.
+ *
+ * @module auth/crypto
+ */
+import { createCipheriv, createDecipheriv, createHmac, hkdfSync, randomBytes, timingSafeEqual } from 'node:crypto';
+const PREFIX = { code: 'pdc1.', access: 'pda1.', refresh: 'pdr1.' };
+export const MIN_SECRET_LENGTH = 32;
+export function deriveKeys(secret) {
+    if (typeof secret !== 'string' || secret.length < MIN_SECRET_LENGTH) {
+        throw new Error(`MCP_OAUTH_SECRET debe tener al menos ${MIN_SECRET_LENGTH} caracteres.`);
+    }
+    const salt = Buffer.from('pharmadate-mcp/oauth/v1');
+    return {
+        enc: Buffer.from(hkdfSync('sha256', secret, salt, 'enc', 32)),
+        mac: Buffer.from(hkdfSync('sha256', secret, salt, 'mac', 32)),
+    };
+}
+const b64u = (b) => b.toString('base64url');
+/** Cifra un objeto JSON en un token opaco con el prefijo de su tipo. */
+export function seal(kind, payload, keys) {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', keys.enc, iv);
+    cipher.setAAD(Buffer.from(kind));
+    const data = Buffer.concat([cipher.update(JSON.stringify(payload), 'utf8'), cipher.final()]);
+    return PREFIX[kind] + b64u(Buffer.concat([iv, cipher.getAuthTag(), data]));
+}
+/** Descifra y verifica. Devuelve `null` si el token esta manipulado, es de otro tipo o no es nuestro. */
+export function open(kind, token, keys) {
+    if (typeof token !== 'string' || !token.startsWith(PREFIX[kind]) || token.length > 8_192)
+        return null;
+    try {
+        const raw = Buffer.from(token.slice(PREFIX[kind].length), 'base64url');
+        if (raw.length < 12 + 16 + 2)
+            return null;
+        const decipher = createDecipheriv('aes-256-gcm', keys.enc, raw.subarray(0, 12));
+        decipher.setAAD(Buffer.from(kind));
+        decipher.setAuthTag(raw.subarray(12, 28));
+        const json = Buffer.concat([decipher.update(raw.subarray(28)), decipher.final()]).toString('utf8');
+        return JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+}
+/** Si el texto parece un token del OAuth del MCP (de cualquier tipo). */
+export function looksLikeMcpToken(token) {
+    return Object.values(PREFIX).some((p) => token.startsWith(p));
+}
+/** Firma un objeto: `base64url(json).base64url(hmac)`. Es el `client_id` del registro dinamico. */
+export function sign(payload, keys) {
+    const body = b64u(Buffer.from(JSON.stringify(payload)));
+    const mac = createHmac('sha256', keys.mac).update(body).digest();
+    return `${body}.${b64u(mac)}`;
+}
+export function verify(signed, keys) {
+    if (typeof signed !== 'string' || signed.length > 8_192)
+        return null;
+    const i = signed.lastIndexOf('.');
+    if (i <= 0)
+        return null;
+    const body = signed.slice(0, i);
+    const mac = Buffer.from(signed.slice(i + 1), 'base64url');
+    const expected = createHmac('sha256', keys.mac).update(body).digest();
+    if (mac.length !== expected.length || !timingSafeEqual(mac, expected))
+        return null;
+    try {
+        return JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/auth/login-page.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Pagina de login del OAuth del MCP: el usuario pega su API key de Pharmadate.
+ *
+ * HTML + CSS en linea, sin JavaScript. Todos los textos que vienen de fuera (nombre del cliente, errores) se escapan.
+ * La respuesta lleva `frame-ancestors 'none'` (anti-clickjacking) y `no-store`. No lleva `form-action`: Chrome lo aplica
+ * tambien a la redireccion posterior y bloquearia la vuelta al cliente (claude.ai, localhost...).
+ *
+ * @module auth/login-page
+ */
+export interface LoginPageParams {
+    clientId: string;
+    redirectUri: string;
+    codeChallenge: string;
+    scope?: string | undefined;
+    state?: string | undefined;
+    resource?: string | undefined;
+    clientName?: string | undefined;
+    errorMessage?: string | undefined;
+}
+export declare function escapeHtml(valor: string): string;
+export declare const LOGIN_PATH = "/oauth/login";
+export declare function renderLoginPage(p: LoginPageParams): string;
+export declare function loginPageHeaders(): Record<string, string>;

package/dist/auth/login-page.js

@@ -0,0 +1,67 @@
+/**
+ * Pagina de login del OAuth del MCP: el usuario pega su API key de Pharmadate.
+ *
+ * HTML + CSS en linea, sin JavaScript. Todos los textos que vienen de fuera (nombre del cliente, errores) se escapan.
+ * La respuesta lleva `frame-ancestors 'none'` (anti-clickjacking) y `no-store`. No lleva `form-action`: Chrome lo aplica
+ * tambien a la redireccion posterior y bloquearia la vuelta al cliente (claude.ai, localhost...).
+ *
+ * @module auth/login-page
+ */
+export function escapeHtml(valor) {
+    return valor.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+}
+const hidden = (name, value) => value === undefined || value === '' ? '' : `<input type="hidden" name="${name}" value="${escapeHtml(value)}">`;
+export const LOGIN_PATH = '/oauth/login';
+export function renderLoginPage(p) {
+    const cliente = escapeHtml(p.clientName || 'tu asistente de IA');
+    const error = p.errorMessage ? `<div class="error" role="alert">${escapeHtml(p.errorMessage)}</div>` : '';
+    return `<!DOCTYPE html>
+<html lang="es">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex">
+<title>Conectar Pharmadate</title>
+<style>
+  *{box-sizing:border-box}
+  body{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;background:#f1f5f9;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;color:#0f172a}
+  main{width:100%;max-width:420px;margin:16px;background:#fff;border-radius:14px;padding:32px 28px;box-shadow:0 10px 30px rgba(15,23,42,.12)}
+  h1{font-size:1.25rem;margin:0 0 6px}
+  p{margin:0 0 16px;color:#475569;font-size:.92rem;line-height:1.45}
+  label{display:block;font-weight:600;font-size:.85rem;margin-bottom:6px}
+  input[type=password]{width:100%;padding:11px 12px;border:1px solid #cbd5e1;border-radius:8px;font-size:.95rem;font-family:ui-monospace,Menlo,monospace}
+  input[type=password]:focus{outline:2px solid #2563eb;border-color:#2563eb}
+  button{margin-top:16px;width:100%;padding:12px;border:0;border-radius:8px;background:#0f172a;color:#fff;font-size:1rem;font-weight:600;cursor:pointer}
+  button:hover{background:#1e293b}
+  .error{background:#fef2f2;color:#991b1b;border:1px solid #fecaca;border-radius:8px;padding:10px 12px;margin-bottom:16px;font-size:.88rem}
+  .hint{font-size:.8rem;color:#64748b;margin-top:14px}
+  .brand{font-weight:700;letter-spacing:.02em;color:#0f172a;margin-bottom:18px}
+</style>
+</head>
+<body>
+<main>
+  <div class="brand">Pharmadate</div>
+  <h1>Conectar con ${cliente}</h1>
+  <p>${cliente} podra consultar el catalogo, valorar y cursar pedidos y, si eres partner, gestionar tus farmacias, con los permisos de la API key que pegues aqui.</p>
+  ${error}
+  <form method="post" action="${LOGIN_PATH}" autocomplete="off">
+    ${hidden('client_id', p.clientId)}${hidden('redirect_uri', p.redirectUri)}${hidden('code_challenge', p.codeChallenge)}${hidden('scope', p.scope)}${hidden('state', p.state)}${hidden('resource', p.resource)}
+    <label for="api_key">API key de Pharmadate</label>
+    <input id="api_key" name="api_key" type="password" required placeholder="pk_partner_... o pk_live_..." spellcheck="false" autocapitalize="off">
+    <button type="submit">Conectar</button>
+  </form>
+  <p class="hint">Consejo para partners: crea una credencial dedicada &laquo;MCP&raquo; en tu panel (/partner.html) y revocala cuando quieras. Para desconectar basta con rotar o revocar la key. Esta version solo admite keys de partner o de farmacia.</p>
+</main>
+</body>
+</html>`;
+}
+export function loginPageHeaders() {
+    return {
+        'Content-Type': 'text/html; charset=utf-8',
+        'Cache-Control': 'no-store',
+        'X-Frame-Options': 'DENY',
+        'Content-Security-Policy': "default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'; base-uri 'none'",
+        'Referrer-Policy': 'no-referrer',
+        'X-Content-Type-Options': 'nosniff',
+    };
+}

package/dist/auth/oauth-provider.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Proveedor OAuth 2.1 SIN ESTADO del MCP de Pharmadate.
+ *
+ * Estructura tomada de `mcp-nevent/src/auth/oauth-provider.ts`, sin las stores de MongoDB: no hay base de datos y el
+ * servidor no recuerda nada entre peticiones (funciona con varias instancias de Elastic Beanstalk detras del ALB).
+ *
+ * Flujo:
+ *   1. El cliente descubre `/.well-known/oauth-authorization-server` y se registra (`POST /register`, DCR). El
+ *      `client_id` ES la metadata del registro firmada con HMAC ({@link StatelessClientsStore}).
+ *   2. `GET /authorize` -> pagina donde el usuario PEGA SU API KEY. `POST /oauth/login` la valida con `GET /api/v1/ping`.
+ *   3. Se emite un `code` (60 s): la key cifrada con AES-256-GCM + PKCE + client + redirect_uri.
+ *   4. `POST /token`: el SDK comprueba PKCE; aqui se canjea por un access token (1 h) y un refresh token (30 d).
+ *   5. Cada llamada a `/mcp` trae el access token; se descifra y la key se usa contra la API, que es quien autoriza.
+ *
+ * REVOCAR ES ROTAR LA KEY: no hay lista de tokens revocados. Una key rotada o revocada hace que cada llamada de la API
+ * (y cualquier refresco) devuelva 401, y el cliente vuelve a pedir el login. Por eso no se anuncia `revocation_endpoint`.
+ *
+ * El code no es de un solo uso (no hay estado donde marcarlo); lo acotan su vida de 60 s y PKCE (quien lo robe no tiene el
+ * `code_verifier`).
+ *
+ * @module auth/oauth-provider
+ */
+import type { Response } from 'express';
+import type { OAuthServerProvider, AuthorizationParams } from '@modelcontextprotocol/sdk/server/auth/provider.js';
+import type { OAuthRegisteredClientsStore } from '@modelcontextprotocol/sdk/server/auth/clients.js';
+import type { OAuthClientInformationFull, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
+import type { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
+import { type DerivedKeys } from './crypto.js';
+export declare const SCOPE = "mcp:tools";
+export declare const CODE_TTL_S = 60;
+export declare const ACCESS_TTL_S = 3600;
+export declare const REFRESH_TTL_S: number;
+export declare const CHAIN_MAX_S: number;
+/** Resultado de comprobar una API key contra la API. */
+export type KeyCheck = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'invalid' | 'unavailable';
+    message: string;
+};
+export type KeyValidator = (apiKey: string) => Promise<KeyCheck>;
+/** DCR sin base de datos: el client_id lleva la metadata firmada. Todos los clientes son publicos (PKCE, sin secreto). */
+export declare class StatelessClientsStore implements OAuthRegisteredClientsStore {
+    private readonly keys;
+    constructor(keys: DerivedKeys);
+    getClient(clientId: string): OAuthClientInformationFull | undefined;
+    registerClient(client: Omit<OAuthClientInformationFull, 'client_id' | 'client_id_issued_at'>): OAuthClientInformationFull;
+}
+export interface OAuthProviderOptions {
+    secret: string;
+    /** Comprueba una API key (GET /api/v1/ping). */
+    validateKey: KeyValidator;
+    /** URL canonica del recurso MCP (p. ej. https://www.pharmadatepedido.es/mcp). */
+    resourceUrl: URL;
+}
+export declare class PharmadateOAuthProvider implements OAuthServerProvider {
+    readonly clientsStore: StatelessClientsStore;
+    private readonly keys;
+    private readonly validateKey;
+    readonly resourceUrl: URL;
+    constructor(options: OAuthProviderOptions);
+    /** GET /authorize: muestra la pagina donde se pega la API key. */
+    authorize(client: OAuthClientInformationFull, params: AuthorizationParams, res: Response): Promise<void>;
+    /**
+     * POST /oauth/login: valida la API key y, si es buena, redirige al cliente con un code.
+     * `redirect_uri` se vuelve a comprobar contra las registradas en el client_id (anti open-redirect).
+     */
+    handleLoginPost(form: {
+        api_key?: string;
+        client_id?: string;
+        redirect_uri?: string;
+        code_challenge?: string;
+        scope?: string;
+        state?: string;
+        resource?: string;
+    }, res: Response): Promise<void>;
+    challengeForAuthorizationCode(client: OAuthClientInformationFull, authorizationCode: string): Promise<string>;
+    exchangeAuthorizationCode(client: OAuthClientInformationFull, authorizationCode: string, _codeVerifier?: string, redirectUri?: string, resource?: URL): Promise<OAuthTokens>;
+    exchangeRefreshToken(client: OAuthClientInformationFull, refreshToken: string, scopes?: string[], resource?: URL): Promise<OAuthTokens>;
+    /** Descifra un access token. Lo usa `requireBearerAuth` del SDK. */
+    verifyAccessToken(token: string): Promise<AuthInfo>;
+    private issue;
+}

package/dist/auth/oauth-provider.js

@@ -0,0 +1,188 @@
+import { InvalidGrantError, InvalidTokenError, InvalidRequestError, ServerError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
+import { deriveKeys, open, seal, sign, verify } from './crypto.js';
+import { loginPageHeaders, renderLoginPage } from './login-page.js';
+import { logger } from '../logger.js';
+export const SCOPE = 'mcp:tools';
+export const CODE_TTL_S = 60;
+export const ACCESS_TTL_S = 3_600;
+export const REFRESH_TTL_S = 30 * 24 * 3_600;
+export const CHAIN_MAX_S = 90 * 24 * 3_600;
+const MAX_REDIRECT_URIS = 10;
+const MAX_REDIRECT_URI_LENGTH = 512;
+const nowS = () => Math.floor(Date.now() / 1000);
+/** DCR sin base de datos: el client_id lleva la metadata firmada. Todos los clientes son publicos (PKCE, sin secreto). */
+export class StatelessClientsStore {
+    keys;
+    constructor(keys) {
+        this.keys = keys;
+    }
+    getClient(clientId) {
+        const meta = verify(clientId, this.keys);
+        if (!meta || !Array.isArray(meta.redirect_uris))
+            return undefined;
+        return {
+            client_id: clientId,
+            client_id_issued_at: meta.iat,
+            redirect_uris: meta.redirect_uris,
+            client_name: meta.client_name,
+            grant_types: meta.grant_types,
+            response_types: meta.response_types,
+            token_endpoint_auth_method: 'none',
+            scope: meta.scope,
+        };
+    }
+    registerClient(client) {
+        const uris = (client.redirect_uris ?? []).map(String);
+        if (uris.length === 0 || uris.length > MAX_REDIRECT_URIS || uris.some((u) => u.length > MAX_REDIRECT_URI_LENGTH)) {
+            throw new InvalidRequestError(`redirect_uris: entre 1 y ${MAX_REDIRECT_URIS} URLs de hasta ${MAX_REDIRECT_URI_LENGTH} caracteres.`);
+        }
+        const meta = {
+            redirect_uris: uris,
+            grant_types: ['authorization_code', 'refresh_token'],
+            response_types: ['code'],
+            token_endpoint_auth_method: 'none',
+            iat: nowS(),
+        };
+        if (client.client_name)
+            meta.client_name = String(client.client_name).slice(0, 100);
+        if (client.scope)
+            meta.scope = String(client.scope).slice(0, 100);
+        const clientId = sign(meta, this.keys);
+        return { ...this.getClient(clientId) };
+    }
+}
+export class PharmadateOAuthProvider {
+    clientsStore;
+    keys;
+    validateKey;
+    resourceUrl;
+    constructor(options) {
+        this.keys = deriveKeys(options.secret);
+        this.clientsStore = new StatelessClientsStore(this.keys);
+        this.validateKey = options.validateKey;
+        this.resourceUrl = options.resourceUrl;
+    }
+    /** GET /authorize: muestra la pagina donde se pega la API key. */
+    async authorize(client, params, res) {
+        res.set(loginPageHeaders());
+        res.send(renderLoginPage({
+            clientId: client.client_id,
+            redirectUri: params.redirectUri,
+            codeChallenge: params.codeChallenge,
+            scope: params.scopes?.join(' '),
+            state: params.state,
+            resource: params.resource?.toString(),
+            clientName: client.client_name,
+        }));
+    }
+    /**
+     * POST /oauth/login: valida la API key y, si es buena, redirige al cliente con un code.
+     * `redirect_uri` se vuelve a comprobar contra las registradas en el client_id (anti open-redirect).
+     */
+    async handleLoginPost(form, res) {
+        const client = typeof form.client_id === 'string' ? this.clientsStore.getClient(form.client_id) : undefined;
+        if (!client || typeof form.redirect_uri !== 'string' || !client.redirect_uris.map(String).includes(form.redirect_uri)) {
+            res.status(400).type('text/plain').send('Cliente o redirect_uri no validos.');
+            return;
+        }
+        const challenge = form.code_challenge ?? '';
+        if (!/^[A-Za-z0-9_-]{43,128}$/.test(challenge)) {
+            res.status(400).type('text/plain').send('Falta el code_challenge PKCE (S256).');
+            return;
+        }
+        const volver = (errorMessage) => {
+            res.status(200).set(loginPageHeaders());
+            res.send(renderLoginPage({
+                clientId: client.client_id,
+                redirectUri: form.redirect_uri,
+                codeChallenge: challenge,
+                scope: form.scope,
+                state: form.state,
+                resource: form.resource,
+                clientName: client.client_name,
+                errorMessage,
+            }));
+        };
+        const apiKey = typeof form.api_key === 'string' ? form.api_key.trim() : '';
+        if (!apiKey || apiKey.length > 200 || /\s/.test(apiKey)) {
+            volver('Pega tu API key de Pharmadate.');
+            return;
+        }
+        const check = await this.validateKey(apiKey);
+        if (!check.ok) {
+            volver(check.reason === 'invalid' ? 'La API key no es valida, esta revocada o es de un tipo no admitido. Revisala y vuelve a intentarlo.' : 'No se ha podido comprobar la API key ahora mismo. Vuelve a intentarlo en un momento.');
+            return;
+        }
+        const scopes = (form.scope ?? '').split(' ').filter(Boolean);
+        const payload = {
+            k: apiKey,
+            cid: client.client_id,
+            ru: form.redirect_uri,
+            cc: challenge,
+            sc: scopes.length ? scopes : [SCOPE],
+            exp: nowS() + CODE_TTL_S,
+            ...(form.resource ? { res: form.resource } : {}),
+        };
+        const code = seal('code', payload, this.keys);
+        const destino = new URL(form.redirect_uri);
+        destino.searchParams.set('code', code);
+        if (form.state)
+            destino.searchParams.set('state', form.state);
+        logger.info({ client: client.client_name ?? 'unknown' }, 'oauth login ok');
+        res.set('Cache-Control', 'no-store').redirect(302, destino.toString());
+    }
+    async challengeForAuthorizationCode(client, authorizationCode) {
+        const c = open('code', authorizationCode, this.keys);
+        if (!c || c.exp < nowS() || c.cid !== client.client_id)
+            throw new InvalidGrantError('Codigo de autorizacion invalido o caducado.');
+        return c.cc;
+    }
+    async exchangeAuthorizationCode(client, authorizationCode, _codeVerifier, redirectUri, resource) {
+        const c = open('code', authorizationCode, this.keys);
+        if (!c || c.exp < nowS())
+            throw new InvalidGrantError('Codigo de autorizacion invalido o caducado.');
+        if (c.cid !== client.client_id)
+            throw new InvalidGrantError('El codigo no se emitio para este cliente.');
+        if (redirectUri && redirectUri !== c.ru)
+            throw new InvalidGrantError('redirect_uri no coincide con el de la autorizacion.');
+        return this.issue(c.k, client.client_id, c.sc, resource?.toString() ?? c.res, nowS());
+    }
+    async exchangeRefreshToken(client, refreshToken, scopes, resource) {
+        const r = open('refresh', refreshToken, this.keys);
+        if (!r || r.exp < nowS())
+            throw new InvalidGrantError('Refresh token invalido o caducado.');
+        if (r.cid !== client.client_id)
+            throw new InvalidGrantError('El refresh token no se emitio para este cliente.');
+        if (nowS() - r.cs > CHAIN_MAX_S)
+            throw new InvalidGrantError('La sesion ha superado su vida maxima; vuelve a iniciar sesion.');
+        if (scopes?.length && scopes.some((s) => !r.sc.includes(s)))
+            throw new InvalidGrantError('Los scopes pedidos no son un subconjunto de los concedidos.');
+        // Si la key se ha rotado o revocado, no se renueva: el cliente tiene que volver a autorizar
+        const check = await this.validateKey(r.k);
+        if (!check.ok) {
+            if (check.reason === 'invalid')
+                throw new InvalidGrantError('La API key ya no es valida; vuelve a iniciar sesion.');
+            throw new ServerError('No se pudo comprobar la API key; reintenta.');
+        }
+        return this.issue(r.k, client.client_id, scopes?.length ? scopes : r.sc, resource?.toString() ?? r.res, r.cs);
+    }
+    /** Descifra un access token. Lo usa `requireBearerAuth` del SDK. */
+    async verifyAccessToken(token) {
+        const a = open('access', token, this.keys);
+        if (!a)
+            throw new InvalidTokenError('Token invalido.');
+        if (a.exp < nowS())
+            throw new InvalidTokenError('Token caducado.');
+        const info = { token, clientId: a.cid, scopes: a.sc, expiresAt: a.exp, extra: { apiKey: a.k } };
+        if (a.res)
+            info.resource = new URL(a.res);
+        return info;
+    }
+    issue(apiKey, clientId, scopes, resource, chainStart) {
+        const now = nowS();
+        const base = { k: apiKey, cid: clientId, sc: scopes, ...(resource ? { res: resource } : {}) };
+        const access = seal('access', { ...base, exp: now + ACCESS_TTL_S }, this.keys);
+        const refresh = seal('refresh', { ...base, exp: Math.min(now + REFRESH_TTL_S, chainStart + CHAIN_MAX_S), cs: chainStart }, this.keys);
+        return { access_token: access, token_type: 'bearer', expires_in: ACCESS_TTL_S, scope: scopes.join(' '), refresh_token: refresh };
+    }
+}