@cayotv/sso 0.0.0 → 0.1.0

package/README.md

@@ -1 +1,92 @@
-# @cayotv/sso — reserva del nombre. Usa 0.1.0 o posterior.
+# @cayotv/sso
+
+Librería de las apps detrás del gateway del SSO de CayoTV (D22). Valida el access token que el gateway pone en `Authorization`, con las doce comprobaciones del contrato ([`docs/12-contrato-apps.md`](../../docs/12-contrato-apps.md), §3). Cada rechazo lleva su código.
+
+Cómo integrar una app: [`docs/13-integracion-sso.md`](../../docs/13-integracion-sso.md).
+
+## Instalación
+
+```sh
+npm install --save-exact @cayotv/sso@0.1.0
+```
+
+Siempre con la versión exacta: una versión nueva se adopta a propósito, no en un `npm install` cualquiera. El paquete es público, pero no lleva nada secreto: el issuer y el JWKS ya lo son.
+
+## Uso
+
+```ts
+import { verifyRequest, SsoError } from "@cayotv/sso";
+
+const config = {
+  issuer: "https://cognito-idp.<region>.amazonaws.com/<pool>",
+  clientId: "<client de la app>",
+  appId: "opta-media",
+};
+
+try {
+  const identity = await verifyRequest(request.headers, config); // { sub, role, apps, managedApps }
+} catch (err) {
+  if (err instanceof SsoError) {
+    // err.code (p. ej. "expired") y err.status (401 o 403)
+  }
+  throw err; // otro error (el JWKS no responde): la app falla en cerrado
+}
+```
+
+- **Configuración obligatoria:** `issuer`, `clientId` y `appId`. Sin ellos, `verifyRequest` lanza un `Error` (no un `SsoError`): es un fallo de programación, no un 401.
+- **El JWKS** se pide a `<issuer>/.well-known/jwks.json`, se guarda en caché y se vuelve a pedir ante un `kid` desconocido.
+- **`allowAnyApp: true`** es solo para el portal, que admite a cualquiera con sesión. Una app nunca lo pone.
+
+## Operaciones sensibles: `checkNow`
+
+```ts
+import { checkNow } from "@cayotv/sso";
+
+const identity = await verifyRequest(request.headers, config); // primero, como siempre
+const check = await checkNow(request.headers); // { allowed: true } o { allowed: false, reason }
+if (!check.allowed) return new Response(null, { status: 403 });
+// ...la operación sensible
+```
+
+- Pregunta al gateway (`http://sso-gateway:8081/_sso/check`, en la red del host) si el usuario puede todavía, con los datos del directorio y no los del token (contrato, §6).
+- Solo antes de la operación concreta, nunca en cada petición.
+- **Nunca lanza.** Si el gateway no responde, o responde algo inesperado, da `{ allowed: false, reason: "unavailable" }`.
+- `url`, `timeoutMs` (2 s) y `fetch` se pueden cambiar en el segundo argumento.
+
+## Next.js
+
+```ts
+import { headers } from "next/headers";
+import { pageIdentity, withIdentity } from "@cayotv/sso/next";
+
+// Página de servidor: la identidad o null.
+const identity = await pageIdentity(await headers(), config);
+
+// Route Handler: 401 o 403 con {"error": <código>} sin llegar al handler.
+export const GET = withIdentity(config, async (req, identity) => Response.json({ sub: identity.sub }));
+```
+
+La identidad se comprueba en cada página y en cada Route Handler, nunca en el middleware de Next (D20).
+
+## Selector de apps (React)
+
+```tsx
+import { AppsSelector } from "@cayotv/sso/react";
+
+<AppsSelector withLogout />
+```
+
+Solo envuelve el Web Component que sirve el gateway en `/_sso/selector.js` (contrato, §7). `react` es una dependencia opcional del paquete.
+
+## Tests
+
+`npm test -w sdk/js` pasa, entre otros, los vectores del contrato (`sdk/test-vectors/vectors.json`) con el código exacto de cada caso.
+
+## Publicación
+
+El paquete se publica en npm con el workflow `release-sdk`, por publicación de confianza (OIDC), sin tokens y sin procedencia (el repositorio es privado). El workflow solo propone la versión: no se publica hasta que un mantenedor la aprueba con 2FA (staged publishing). Lo que se publica no es este directorio: `npm run stage -w sdk/js` compila `src/` a `dist/` y prepara `.publish/`, con un `package.json` generado a partir de este que exporta `dist/`. `npm run check:package -w sdk/js` comprueba qué ficheros entran y que lo compilado carga. Las dos cosas corren en cada `ci`.
+
+Para publicar una versión:
+1. Una PR que sube `version` en `package.json` y en los ejemplos de instalación, el de arriba y el de `docs/13-integracion-sso.md` (§3).
+2. Fusionada y con `ci` en verde, un operador lanza `release-sdk` (Actions → Run workflow). Propone la versión de la punta de `main` con `npm stage publish` y crea el tag `sdk-v<version>`.
+3. Un mantenedor del paquete en npm la revisa y la aprueba con 2FA: npmjs.com → `@cayotv/sso` → *Staged Packages*, o `npm stage list @cayotv/sso` y `npm stage approve <stage-id>`. Hasta entonces no está publicada. Si se rechaza (`npm stage reject`), el tag se queda y la siguiente sube la versión.

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+import { type JWTVerifyGetKey } from "jose";
+/**
+ * Validacion del access token que el gateway pone en `Authorization`, segun el
+ * contrato de las apps (docs/12-contrato-apps.md, §3; D22). Las doce
+ * comprobaciones, en su orden, y cada fallo con su codigo. Los vectores de
+ * sdk/test-vectors son la prueba de que esto y el contrato dicen lo mismo.
+ *
+ * Sin framework: recibe cualquier objeto con `get(nombre)`, como los Headers de
+ * la plataforma web o los de Next.js. El adaptador de Next.js esta en ./next.
+ */
+/** Los codigos del contrato (§3). Del 1 al 10 y el 12 son un 401; el 11, un 403. */
+export type SsoErrorCode = "missing_token" | "malformed_token" | "invalid_token" | "missing_claim" | "wrong_issuer" | "expired" | "not_yet_valid" | "issued_in_future" | "wrong_token_use" | "wrong_client" | "forbidden_app" | "user_mismatch";
+/** El token no vale para esta app. Cualquier otro error (p. ej. el JWKS no responde) no es un SsoError: la app falla en cerrado. */
+export declare class SsoError extends Error {
+    readonly code: SsoErrorCode;
+    readonly status: 401 | 403;
+    constructor(code: SsoErrorCode, detail?: string);
+}
+/** Los claims del token (§4). Sirven para leer; no bastan para una operacion sensible (§6). */
+export interface Identity {
+    sub: string;
+    role: "admin" | "app_manager" | "user";
+    apps: string[];
+    managedApps: string[];
+}
+export interface SsoConfig {
+    /** `iss` exacto del pool: `https://cognito-idp.<region>.amazonaws.com/<pool>`. */
+    issuer: string;
+    /** El client de la app. Cognito lo pone en `client_id`, no en `aud`. */
+    clientId: string;
+    /** El `app_id` de la app en el catalogo. Obligatorio salvo con `allowAnyApp`. */
+    appId?: string;
+    /**
+     * Solo el portal: admite a cualquiera con sesion, como hace el gateway con
+     * el host del portal. Una app nunca lo pone: se saltaria la comprobacion 11.
+     */
+    allowAnyApp?: true;
+    /** Por defecto, el JWKS del pool (`<issuer>/.well-known/jwks.json`), en cache. Para los tests, uno local. */
+    keys?: JWTVerifyGetKey;
+    /** Por defecto, el reloj del sistema. */
+    now?: () => Date;
+}
+/** Lo minimo de unas cabeceras: los Headers web, los de Next.js o un adaptador. */
+export interface HeadersLike {
+    get(name: string): string | null;
+}
+/** La configuracion incompleta es un error de programacion: se lanza siempre, no se convierte en un 401. */
+export declare function checkConfig(config: SsoConfig): void;
+/**
+ * Valida la peticion y devuelve la identidad, o lanza un SsoError con el
+ * codigo del contrato. Hay que llamarla en cada peticion que necesite
+ * identidad, en el backend (§3).
+ */
+export declare function verifyRequest(headers: HeadersLike, config: SsoConfig): Promise<Identity>;
+/** Respuesta de `checkNow`. `invalid_token` y `unavailable` los pone la libreria; el resto, el gateway. */
+export type CheckResult = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: "not_found" | "revoked" | "expired" | "no_app" | "invalid_token" | "unavailable";
+};
+export interface CheckOptions {
+    /** Por defecto, el puerto interno del gateway en la red del host. */
+    url?: string;
+    /** Por defecto, 2 s. */
+    timeoutMs?: number;
+    /** Para los tests. */
+    fetch?: typeof fetch;
+}
+export declare const DEFAULT_CHECK_URL = "http://sso-gateway:8081/_sso/check";
+/**
+ * Comprobacion en tiempo real antes de una operacion sensible (contrato, §6;
+ * D22): el gateway relee del directorio si este usuario puede todavia usar la
+ * app. Se llama despues de `verifyRequest` y solo antes de la operacion
+ * concreta, nunca en cada peticion. **Nunca lanza y nunca da `allowed: true`
+ * por un fallo:** si el gateway no responde o responde algo inesperado, la
+ * respuesta es `{ allowed: false, reason: "unavailable" }` y la operacion no se
+ * hace.
+ */
+export declare function checkNow(headers: HeadersLike, options?: CheckOptions): Promise<CheckResult>;

package/dist/index.js

@@ -0,0 +1,167 @@
+import { createRemoteJWKSet, errors, jwtVerify } from "jose";
+/** El token no vale para esta app. Cualquier otro error (p. ej. el JWKS no responde) no es un SsoError: la app falla en cerrado. */
+export class SsoError extends Error {
+    code;
+    status;
+    constructor(code, detail) {
+        super(detail ?? code);
+        this.code = code;
+        this.name = "SsoError";
+        this.status = code === "forbidden_app" ? 403 : 401;
+    }
+}
+/** Margen para `iat` (§3, comprobacion 8). `exp` y `nbf` van sin margen. */
+const IAT_SKEW_S = 5;
+const BEARER = /^Bearer ([A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)$/;
+const REQUIRED = ["sub", "exp", "iat", "token_use", "client_id"];
+const remoteKeys = new Map();
+function keysFor(config) {
+    if (config.keys)
+        return config.keys;
+    let keys = remoteKeys.get(config.issuer);
+    if (!keys) {
+        // jose vuelve a pedirlo ante un kid desconocido, con un tiempo minimo entre peticiones.
+        keys = createRemoteJWKSet(new URL(`${config.issuer}/.well-known/jwks.json`), { timeoutDuration: 3000 });
+        remoteKeys.set(config.issuer, keys);
+    }
+    return keys;
+}
+/** La configuracion incompleta es un error de programacion: se lanza siempre, no se convierte en un 401. */
+export function checkConfig(config) {
+    if (!/^https:\/\/\S+[^/]$/.test(config.issuer ?? ""))
+        throw new Error("@cayotv/sso: falta issuer, o no es una URL https sin barra final");
+    if (!config.clientId)
+        throw new Error("@cayotv/sso: falta clientId");
+    // Desde JavaScript podria llegar cualquier cosa ("false", 1): solo vale true, y lo demas se rechaza.
+    if (config.allowAnyApp !== undefined && config.allowAnyApp !== true)
+        throw new Error("@cayotv/sso: allowAnyApp solo admite true");
+    if (config.allowAnyApp === true) {
+        if (config.appId !== undefined)
+            throw new Error("@cayotv/sso: appId y allowAnyApp no van juntos");
+    }
+    else if (!config.appId) {
+        throw new Error("@cayotv/sso: falta appId");
+    }
+}
+const strings = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === "string") : []);
+/** Traduce un error de jose a su codigo. Lo que no es culpa del token (red, JWKS roto) se relanza. */
+function codeOf(err) {
+    if (err instanceof errors.JWTExpired)
+        return "expired";
+    if (err instanceof errors.JWTClaimValidationFailed) {
+        if (err.reason === "missing")
+            return "missing_claim";
+        if (err.claim === "iss")
+            return "wrong_issuer";
+        if (err.claim === "nbf")
+            return "not_yet_valid";
+        return "invalid_token";
+    }
+    if (err instanceof errors.JWSSignatureVerificationFailed ||
+        err instanceof errors.JOSEAlgNotAllowed ||
+        err instanceof errors.JWKSNoMatchingKey ||
+        err instanceof errors.JWKSMultipleMatchingKeys ||
+        err instanceof errors.JWSInvalid ||
+        err instanceof errors.JWTInvalid ||
+        err instanceof errors.JOSENotSupported) {
+        return "invalid_token";
+    }
+    return null;
+}
+/**
+ * Valida la peticion y devuelve la identidad, o lanza un SsoError con el
+ * codigo del contrato. Hay que llamarla en cada peticion que necesite
+ * identidad, en el backend (§3).
+ */
+export async function verifyRequest(headers, config) {
+    checkConfig(config);
+    const now = config.now ?? (() => new Date());
+    // 1 y 2.
+    const auth = headers.get("authorization");
+    if (auth === null)
+        throw new SsoError("missing_token");
+    const match = BEARER.exec(auth);
+    if (!match)
+        throw new SsoError("malformed_token");
+    // 3 a 7: firma solo RS256, claims obligatorios, iss, exp y nbf.
+    let payload;
+    try {
+        ({ payload } = await jwtVerify(match[1], keysFor(config), {
+            issuer: config.issuer,
+            algorithms: ["RS256"],
+            requiredClaims: REQUIRED,
+            currentDate: now(),
+        }));
+    }
+    catch (err) {
+        const code = codeOf(err);
+        if (!code)
+            throw err;
+        throw new SsoError(code, err.message);
+    }
+    if (typeof payload.sub !== "string" || payload.sub.length === 0)
+        throw new SsoError("missing_claim", "sub vacio");
+    // 8 a 10.
+    if (typeof payload.iat !== "number" || payload.iat > now().getTime() / 1000 + IAT_SKEW_S)
+        throw new SsoError("issued_in_future");
+    if (payload.token_use !== "access")
+        throw new SsoError("wrong_token_use");
+    if (payload.client_id !== config.clientId)
+        throw new SsoError("wrong_client");
+    const role = payload["cayotv:role"];
+    const identity = {
+        sub: payload.sub,
+        role: role === "admin" || role === "app_manager" ? role : "user",
+        apps: strings(payload["cayotv:apps"]),
+        managedApps: strings(payload["cayotv:managed_apps"]),
+    };
+    // 11: la misma regla que el gateway en forward_auth.
+    if (config.allowAnyApp !== true && identity.role !== "admin" && !identity.apps.includes(config.appId))
+        throw new SsoError("forbidden_app");
+    // 12.
+    const user = headers.get("x-auth-user");
+    if (user !== null && user !== identity.sub)
+        throw new SsoError("user_mismatch");
+    return identity;
+}
+export const DEFAULT_CHECK_URL = "http://sso-gateway:8081/_sso/check";
+const GATEWAY_REASONS = new Set(["not_found", "revoked", "expired", "no_app"]);
+/**
+ * Comprobacion en tiempo real antes de una operacion sensible (contrato, §6;
+ * D22): el gateway relee del directorio si este usuario puede todavia usar la
+ * app. Se llama despues de `verifyRequest` y solo antes de la operacion
+ * concreta, nunca en cada peticion. **Nunca lanza y nunca da `allowed: true`
+ * por un fallo:** si el gateway no responde o responde algo inesperado, la
+ * respuesta es `{ allowed: false, reason: "unavailable" }` y la operacion no se
+ * hace.
+ */
+export async function checkNow(headers, options = {}) {
+    const authorization = headers.get("authorization");
+    if (!authorization)
+        return { allowed: false, reason: "invalid_token" };
+    let res;
+    try {
+        res = await (options.fetch ?? fetch)(options.url ?? DEFAULT_CHECK_URL, {
+            method: "GET",
+            headers: { authorization, accept: "application/json" },
+            redirect: "error",
+            signal: AbortSignal.timeout(options.timeoutMs ?? 2000),
+        });
+    }
+    catch {
+        return { allowed: false, reason: "unavailable" };
+    }
+    if (res.status === 401)
+        return { allowed: false, reason: "invalid_token" };
+    if (res.status !== 200)
+        return { allowed: false, reason: "unavailable" };
+    const body = await res.json().catch(() => null);
+    if (typeof body !== "object" || body === null)
+        return { allowed: false, reason: "unavailable" };
+    const { allowed, reason } = body;
+    if (allowed === true)
+        return { allowed: true };
+    if (allowed === false && typeof reason === "string" && GATEWAY_REASONS.has(reason))
+        return { allowed: false, reason: reason };
+    return { allowed: false, reason: "unavailable" };
+}

package/dist/next.d.ts

@@ -0,0 +1,26 @@
+import { type HeadersLike, type Identity, type SsoConfig } from "@cayotv/sso";
+/**
+ * Adaptador para Next.js (App Router; D20, D22). Sin dependencia de `next`: los
+ * Route Handlers reciben un Request web, y en una pagina de servidor las
+ * cabeceras salen de `await headers()`.
+ *
+ * La identidad se comprueba en cada pagina y en cada Route Handler, nunca en el
+ * middleware (`proxy`) de Next: si el middleware se salta, no se abre nada
+ * (D20, «Reglas de uso de Next.js»).
+ */
+/**
+ * Para una pagina de servidor: la identidad, o null si el token no vale. Con
+ * null, la pagina no pinta datos del usuario. Un error que no es del token
+ * (el JWKS no responde) se lanza.
+ *
+ *   const identity = await pageIdentity(await headers(), config);
+ */
+export declare function pageIdentity(headers: HeadersLike, config: SsoConfig): Promise<Identity | null>;
+/**
+ * Envoltorio de un Route Handler: valida y llama al handler con la identidad.
+ * Si el token no vale, responde 401 o 403 con `{"error": <codigo>}` sin llegar
+ * al handler.
+ *
+ *   export const GET = withIdentity(config, async (req, identity) => Response.json({ sub: identity.sub }));
+ */
+export declare function withIdentity<Args extends unknown[]>(config: SsoConfig, handler: (req: Request, identity: Identity, ...args: Args) => Promise<Response>): (req: Request, ...args: Args) => Promise<Response>;

package/dist/next.js

@@ -0,0 +1,48 @@
+import { SsoError, verifyRequest } from "@cayotv/sso";
+/**
+ * Adaptador para Next.js (App Router; D20, D22). Sin dependencia de `next`: los
+ * Route Handlers reciben un Request web, y en una pagina de servidor las
+ * cabeceras salen de `await headers()`.
+ *
+ * La identidad se comprueba en cada pagina y en cada Route Handler, nunca en el
+ * middleware (`proxy`) de Next: si el middleware se salta, no se abre nada
+ * (D20, «Reglas de uso de Next.js»).
+ */
+/**
+ * Para una pagina de servidor: la identidad, o null si el token no vale. Con
+ * null, la pagina no pinta datos del usuario. Un error que no es del token
+ * (el JWKS no responde) se lanza.
+ *
+ *   const identity = await pageIdentity(await headers(), config);
+ */
+export async function pageIdentity(headers, config) {
+    try {
+        return await verifyRequest(headers, config);
+    }
+    catch (err) {
+        if (err instanceof SsoError)
+            return null;
+        throw err;
+    }
+}
+/**
+ * Envoltorio de un Route Handler: valida y llama al handler con la identidad.
+ * Si el token no vale, responde 401 o 403 con `{"error": <codigo>}` sin llegar
+ * al handler.
+ *
+ *   export const GET = withIdentity(config, async (req, identity) => Response.json({ sub: identity.sub }));
+ */
+export function withIdentity(config, handler) {
+    return async (req, ...args) => {
+        let identity;
+        try {
+            identity = await verifyRequest(req.headers, config);
+        }
+        catch (err) {
+            if (err instanceof SsoError)
+                return Response.json({ error: err.code }, { status: err.status });
+            throw err;
+        }
+        return handler(req, identity, ...args);
+    };
+}

package/dist/react.d.ts

@@ -0,0 +1,5 @@
+export declare function AppsSelector({ withLogout }: {
+    withLogout?: boolean;
+}): import("react").ReactElement<{
+    "with-logout": string;
+}, string | import("react").JSXElementConstructor<any>>;

package/dist/react.js

@@ -0,0 +1,25 @@
+"use client";
+import { createElement, useEffect } from "react";
+/**
+ * Selector de apps para React (D22): solo envuelve el Web Component que sirve
+ * el gateway en `/_sso/selector.js` (contrato de las apps, §7). Carga el
+ * script una vez, en el navegador, y pinta `<cayotv-apps>`; el resto (leer
+ * `/_sso/apps`, recargar ante un 401, enlaces solo https) lo hace el
+ * componente. Sin JSX, para no obligar a la app a compilar el paquete.
+ * `"use client"`: en el App Router de Next se puede usar desde un layout o una
+ * pagina de servidor sin envolverlo.
+ *
+ *   <AppsSelector withLogout />
+ */
+const SCRIPT_SRC = "/_sso/selector.js";
+export function AppsSelector({ withLogout = false }) {
+    useEffect(() => {
+        if (customElements.get("cayotv-apps") || document.querySelector(`script[src="${SCRIPT_SRC}"]`))
+            return;
+        const script = document.createElement("script");
+        script.type = "module";
+        script.src = SCRIPT_SRC;
+        document.head.append(script);
+    }, []);
+    return createElement("cayotv-apps", withLogout ? { "with-logout": "" } : null);
+}

package/package.json

@@ -1,7 +1,43 @@
 {
   "name": "@cayotv/sso",
-  "version": "0.0.0",
-  "description": "Reserva del nombre. Usa 0.1.0 o posterior.",
+  "version": "0.1.0",
+  "description": "Libreria de las apps detras del gateway del SSO de CayoTV (D22): validacion del access token segun el contrato (docs/12), adaptador para Next.js y selector de apps para React",
   "license": "UNLICENSED",
-  "repository": { "type": "git", "url": "git+https://github.com/CayoTV/cayotv-sso.git", "directory": "sdk/js" }
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CayoTV/cayotv-sso.git",
+    "directory": "sdk/js"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "default": "./dist/next.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "jose": "6.2.12"
+  },
+  "peerDependencies": {
+    "react": ">=19"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  }
 }