@dacyti-gsi/auth 0.2.0 → 0.3.0

package/src/index.ts

@@ -1,673 +1,671 @@
-import { resolveOptions, validateOptions } from "./config";
-import {
-  authorizationUrl,
-  buildSession,
-  discover,
-  exchangeCode,
-  fetchUserInfo,
-  refreshOnce,
-  refreshTokens,
-  sessionFromPayload,
-  type TokenSet,
-} from "./core";
-import { isCredentialRejected, SSOError } from "./errors";
-import { createAuthorizationAttempt, statesMatch } from "./pkce";
-import {
-  openSession,
-  type SessionPayload,
-  sealSession,
-} from "./session-cookie";
-import type { SSOClientOptions, SSOSession } from "./types";
-
-export {
-  type ResolvedSSOOptions,
-  resolveOptions,
-  validateOptions,
-} from "./config";
-export {
-  clearDiscoveryCache,
-  clientCredentialsToken,
-  introspectToken,
-} from "./core";
-export {
-  SSOConfigError,
-  SSOError,
-  SSOForbiddenError,
-  SSOProtocolError,
-} from "./errors";
-export {
-  type AccessPolicy,
-  authorize,
-  SSOAuthRequiredError,
-  SSOMfaRequiredError,
-} from "./policy";
-export type {
-  AuthMethod,
-  SSOClientOptions,
-  SSOSession,
-  SSOUser,
-} from "./types";
-
-/**
- * `offline_access` va por defecto a propósito.
- *
- * Es lo que hace que el portal emita un `refresh_token`. Sin él, el access token
- * dura quince minutos y no hay forma de renovarlo: la aplicación se quedaría sin
- * acceso a las APIs a los quince minutos y solo podría recuperarlo volviendo a
- * mandar al usuario a autenticarse.
- */
-const DEFAULT_SCOPES = ["openid", "profile", "email", "offline_access"];
-const DEFAULT_BASE_PATH = "/api/sso";
-const DEFAULT_COOKIE = "__Host-sso_session";
-const DEFAULT_MAX_AGE = 7 * 24 * 60 * 60;
-
-/**
- * Ventana de gracia con el portal caído.
- *
- * Cuando el portal no responde, la sesión se sirve de la cookie sin poder
- * revalidar (fail-open deliberado por disponibilidad). Sin tope, una caída
- * prolongada congelaría autorizaciones —incluidos roles ya revocados— hasta
- * agotar la cookie. Pasada esta holgura desde que caducó el acceso, la sesión
- * local deja de aceptarse y se pide autenticarse de nuevo.
- */
-export const MAX_STALE_SECONDS = 60 * 60;
-
-let lastStaleWarningAt = 0;
-
-/**
- * Si una sesión en caché superó la ventana de gracia, avisa (como mucho una
- * vez por minuto) y pide tratarla como terminada.
- */
-export function warnIfStaleSession(expiresAtSeconds: number): boolean {
-  if (Date.now() / 1000 - expiresAtSeconds <= MAX_STALE_SECONDS) return false;
-
-  if (Date.now() - lastStaleWarningAt > 60_000) {
-    lastStaleWarningAt = Date.now();
-    console.warn(
-      "[dacyti-auth] el portal no responde y la sesión en caché superó la ventana de gracia: se exige autenticarse de nuevo en lugar de servir permisos congelados.",
-    );
-  }
-
-  return true;
-}
-
-/**
- * Cookie temporal donde viven el verifier y el state entre ida y vuelta. Lleva el `state` en el
- * nombre: con una sola cookie, abrir dos pestañas a la vez haría que la segunda pisara el intento
- * de la primera y esta fallara al volver.
- */
-const ATTEMPT_COOKIE = "sso_attempt";
-const ATTEMPT_MAX_AGE = 10 * 60;
-const STATE_SHAPE = /^[A-Za-z0-9_-]{8,64}$/;
-const attemptCookieName = (state: string) => `${ATTEMPT_COOKIE}_${state}`;
-
-/**
- * Los navegadores descartan sin avisar una cookie que pasa de ~4 KB, y la sesión guarda tres
- * tokens: si algún día no cabe, el síntoma sería un bucle infinito de login. Mejor un error claro.
- */
-const MAX_COOKIE_BYTES = 4000;
-
-export type ResolvedSession<Permission extends string = string> = {
-  session: SSOSession<Permission>;
-  /**
-   * Cookie nueva, ya sellada. `null` si nada cambió y la anterior sigue valiendo.
-   *
-   * Quien pueda escribir cookies —una Server Action, un route handler— debe
-   * guardarla; quien no pueda, al menos tiene la sesión correcta para esta
-   * respuesta.
-   */
-  cookie: string | null;
-};
-
-export type SSOClient<Permission extends string = string> = {
-  readonly basePath: string;
-  readonly cookieName: string;
-  /** Duración de la sesión local, en segundos. */
-  readonly sessionMaxAge: number;
-
-  /** URL a la que enviar a alguien para autenticarse. */
-  signInPath(returnTo?: string): string;
-  /** URL para cerrar la sesión local y la del portal. */
-  signOutPath(): string;
-
-  /** Reconstruye la sesión desde la cookie. `null` si no hay o caducó. */
-  readSession(
-    cookieValue: string | undefined,
-  ): Promise<SSOSession<Permission> | null>;
-
-  /**
-   * Sesión al día: renueva el acceso caducado y, si se pide, vuelve a consultar
-   * los permisos al portal.
-   *
-   * `readSession` es un descifrado local y no habla con el portal, así que sirve
-   * una foto que puede tener días. Esto es lo contrario: comprueba contra el
-   * portal y devuelve permisos vivos.
-   */
-  resolveSession(
-    cookieValue: string | undefined,
-    options?: { revalidate?: boolean },
-  ): Promise<ResolvedSession<Permission> | null>;
-
-  /** Atiende las rutas del cliente. Devuelve `null` si la ruta no le compete. */
-  handleRequest(request: Request): Promise<Response | null>;
-};
-
-/**
- * Declara el cliente del portal.
- *
- * Sin ceremonia: lo que no se pasa se lee del entorno.
- *
- * ```ts
- * export const sso = defineSSO({ permissions: ["documentos:crear", "documentos:anular"] });
- * // issuer ← SSO_ISSUER, clientId ← SSO_CLIENT_ID,
- * // clientSecret ← SSO_CLIENT_SECRET, secret ← SSO_SECRET
- * ```
- *
- * Pasar `permissions` como tupla `as const` hace que `can()` autocomplete y que
- * un permiso mal escrito falle al compilar, en lugar de devolver `false` en
- * silencio en producción.
- */
-export function defineSSO<const Permission extends string = string>(
-  options: SSOClientOptions<Permission>,
-): SSOClient<Permission> {
-  const resolved = resolveOptions(options);
-  validateOptions(resolved);
-
-  const basePath = (resolved.basePath ?? DEFAULT_BASE_PATH).replace(/\/$/, "");
-  const cookieName = resolved.cookieName ?? DEFAULT_COOKIE;
-  const scopes = resolved.scopes ?? DEFAULT_SCOPES;
-  const maxAge = resolved.sessionMaxAge ?? DEFAULT_MAX_AGE;
-
-  /**
-   * Origen público de la aplicación.
-   *
-   * Se deduce de la petición para no obligar a configurar una variable más. Se
-   * respeta `X-Forwarded-*` porque detrás de un proxy la URL de la petición
-   * lleva el host interno, y el `redirect_uri` resultante no coincidiría con el
-   * registrado.
-   */
-  function originOf(request: Request): string {
-    if (resolved.appUrl) return resolved.appUrl.replace(/\/$/, "");
-
-    const url = new URL(request.url);
-    const host = request.headers.get("x-forwarded-host") ?? url.host;
-    const protocol =
-      request.headers.get("x-forwarded-proto") ?? url.protocol.replace(":", "");
-
-    return `${protocol}://${host}`;
-  }
-
-  const redirectUriFor = (request: Request) =>
-    `${originOf(request)}${basePath}/callback`;
-
-  function readCookie(request: Request, name: string): string | undefined {
-    const header = request.headers.get("cookie");
-    if (!header) return undefined;
-
-    for (const part of header.split(";")) {
-      const trimmed = part.trim();
-      const separator = trimmed.indexOf("=");
-      if (separator > 0 && trimmed.slice(0, separator) === name) {
-        // Una cookie con `%` mal formado no debe tumbar la petición: vale como ausente.
-        try {
-          return decodeURIComponent(trimmed.slice(separator + 1));
-        } catch {
-          return undefined;
-        }
-      }
-    }
-
-    return undefined;
-  }
-
-  function cookieHeader(
-    name: string,
-    value: string,
-    seconds: number,
-    secure: boolean,
-  ): string {
-    const encoded = encodeURIComponent(value);
-    if (encoded.length > MAX_COOKIE_BYTES) {
-      throw new SSOError(
-        `La cookie ${name} pesa ${encoded.length} bytes y el navegador la descartaría (límite ~4096). ` +
-          "Reduce los permisos o scopes de la sesión.",
-      );
-    }
-
-    const attributes = [
-      `${name}=${encoded}`,
-      "Path=/",
-      "HttpOnly",
-      "SameSite=Lax",
-      `Max-Age=${seconds}`,
-    ];
-
-    // `__Host-` exige `Secure` y `Path=/` sin `Domain`: el navegador la
-    // rechaza sin aviso si falta. Se fuerza siempre.
-    if (secure || name.startsWith("__Host-")) attributes.push("Secure");
-
-    return attributes.join("; ");
-  }
-
-  /** El destino tras autenticarse solo puede ser una ruta de esta aplicación. */
-  function safeReturnTo(value: string | null): string {
-    if (!value) return "/";
-    if (!value.startsWith("/")) return "/";
-    if (value.startsWith("//")) return "/";
-    if (value.includes("\\")) return "/";
-
-    return value;
-  }
-
-  async function handleSignIn(request: Request): Promise<Response> {
-    const discovery = await discover(resolved.issuer);
-    const attempt = createAuthorizationAttempt();
-    const returnTo = safeReturnTo(new URL(request.url).searchParams.get("to"));
-
-    const target = authorizationUrl({
-      discovery,
-      clientId: resolved.clientId,
-      redirectUri: redirectUriFor(request),
-      scopes,
-      challenge: attempt.challenge,
-      state: attempt.state,
-    });
-
-    const secure = originOf(request).startsWith("https://");
-    const attemptValue = JSON.stringify({
-      verifier: attempt.verifier,
-      state: attempt.state,
-      returnTo,
-    });
-
-    return new Response(null, {
-      status: 302,
-      headers: {
-        location: target,
-        "set-cookie": cookieHeader(
-          attemptCookieName(attempt.state),
-          attemptValue,
-          ATTEMPT_MAX_AGE,
-          secure,
-        ),
-      },
-    });
-  }
-
-  async function handleCallback(request: Request): Promise<Response> {
-    const url = new URL(request.url);
-    const code = url.searchParams.get("code");
-    const state = url.searchParams.get("state");
-
-    // El `state` forma parte del nombre de la cookie: se valida su forma antes de usarlo.
-    const stateOk = state !== null && STATE_SHAPE.test(state);
-    const raw = stateOk ? readCookie(request, attemptCookieName(state)) : undefined;
-    const secure = originOf(request).startsWith("https://");
-    const clearAttempt = stateOk
-      ? cookieHeader(attemptCookieName(state), "", 0, secure)
-      : null;
-
-    // La persona canceló o el portal rechazó la autorización (`access_denied`, etc.).
-    if (url.searchParams.get("error")) {
-      return new Response(
-        "El portal no autorizó el ingreso. Vuelve a intentarlo.",
-        {
-          status: 403,
-          headers: clearAttempt ? { "set-cookie": clearAttempt } : undefined,
-        },
-      );
-    }
-
-    /**
-     * La cookie del intento la escribió esta aplicación, pero viaja por el
-     * navegador: puede llegar truncada, editada o de una versión anterior del
-     * SDK. Sin este `try`, un `JSON.parse` sobre basura subía como error de
-     * servidor donde lo que corresponde es decir que el intento no vale.
-     */
-    let attempt: { verifier: string; state: string; returnTo: string } | null =
-      null;
-    try {
-      attempt = raw
-        ? (JSON.parse(raw) as {
-            verifier: string;
-            state: string;
-            returnTo: string;
-          })
-        : null;
-    } catch {
-      attempt = null;
-    }
-
-    /**
-     * Sin intento guardado, o con un `state` que no coincide, se aborta.
-     *
-     * Esa comprobación es lo que impide que un tercero fuerce a alguien a
-     * completar un flujo que empezó él: sin ella, un atacante puede hacer que
-     * la víctima acabe con la sesión del atacante iniciada en su navegador.
-     */
-    if (!code || !state || !attempt || !statesMatch(attempt.state, state)) {
-      return new Response("Petición de autenticación inválida o caducada.", {
-        status: 400,
-      });
-    }
-
-    let tokens: TokenSet;
-    let session: SSOSession<Permission>;
-    try {
-      const discovery = await discover(resolved.issuer);
-
-      tokens = await exchangeCode({
-        discovery,
-        clientId: resolved.clientId,
-        clientSecret: resolved.clientSecret,
-        code,
-        verifier: attempt.verifier,
-        redirectUri: redirectUriFor(request),
-      });
-
-      const profile = await fetchUserInfo({
-        discovery,
-        accessToken: tokens.accessToken,
-      });
-      session = buildSession<Permission>(profile, tokens);
-    } catch (error: unknown) {
-      // Código ya usado, caducado o portal caído: el intento no se puede reanudar, pero tampoco
-      // debe llegar al navegador un 500 con el detalle del portal.
-      console.error("[sso] el canje del código falló:", error);
-      return new Response(
-        "No se pudo completar el ingreso con el portal. Vuelve a intentarlo.",
-        {
-          status: 502,
-          headers: clearAttempt ? { "set-cookie": clearAttempt } : undefined,
-        },
-      );
-    }
-
-    const payload: SessionPayload = {
-      sub: session.user.id,
-      email: session.user.email,
-      emailVerified: session.user.emailVerified,
-      name: session.user.name,
-      image: session.user.image,
-      roles: session.roles,
-      permissions: session.permissions,
-      amr: session.amr,
-      accessToken: session.accessToken,
-      refreshToken: tokens.refreshToken,
-      // Se guarda porque `end-session` lo exige para cerrar la sesión del portal.
-      idToken: tokens.idToken,
-      expiresAt: session.expiresAt,
-    };
-
-    return new Response(null, {
-      status: 302,
-      headers: [
-        ["location", `${originOf(request)}${safeReturnTo(attempt.returnTo)}`],
-        [
-          "set-cookie",
-          cookieHeader(
-            cookieName,
-            await sealSession(payload, resolved.secret, maxAge),
-            maxAge,
-            secure,
-          ),
-        ],
-        // El intento ya se consumió: dejarlo vivo permitiría reutilizarlo.
-        ["set-cookie", cookieHeader(attemptCookieName(state), "", 0, secure)],
-      ],
-    });
-  }
-
-  /**
-   * Cierre de sesión en la aplicación **y** en el portal.
-   *
-   * Antes se redirigía a `end_session` sin parámetros, y el portal los exige:
-   * responde con un error de validación, así que la cookie local se borraba y
-   * la sesión del portal seguía viva. El efecto era el peor posible: el usuario
-   * creía haber salido y el siguiente «Entrar» lo dejaba dentro sin pedir nada.
-   *
-   * `id_token_hint` es lo que identifica qué sesión terminar, así que se lee de
-   * la cookie antes de borrarla. Sin él, `end-session` no tiene forma de saber
-   * de quién es la sesión y no se le puede pedir que la cierre.
-   */
-  async function handleSignOut(request: Request): Promise<Response> {
-    const origin = originOf(request);
-    const secure = origin.startsWith("https://");
-
-    const payload = await openSession(
-      readCookie(request, cookieName),
-      resolved.secret,
-    );
-
-    // Sin sesión local no hay nada que cerrar en el portal, así que ni se le
-    // pregunta: salir de una sesión que no existe no necesita una ida y vuelta.
-    let location = origin;
-
-    if (payload?.idToken) {
-      const discovery = await discover(resolved.issuer);
-
-      if (discovery.end_session_endpoint) {
-        const target = new URL(discovery.end_session_endpoint);
-        target.searchParams.set("id_token_hint", payload.idToken);
-        target.searchParams.set("client_id", resolved.clientId);
-
-        /**
-         * Solo se pide volver a la aplicación si se declaró una URI registrada.
-         * El portal rechaza cualquier destino que no lo esté, así que mandarlo
-         * a ciegas cambiaría una salida limpia por una pantalla de error.
-         */
-        if (resolved.postLogoutRedirectUri) {
-          target.searchParams.set(
-            "post_logout_redirect_uri",
-            resolved.postLogoutRedirectUri,
-          );
-        }
-
-        location = target.toString();
-      }
-    }
-
-    return new Response(null, {
-      status: 302,
-      headers: {
-        location,
-        "set-cookie": cookieHeader(cookieName, "", 0, secure),
-      },
-    });
-  }
-
-  /**
-   * Devuelve la sesión al día, hablando con el portal solo cuando hace falta.
-   *
-   * Dos cosas distintas pueden estar rancias:
-   *
-   * - El `access_token`, que dura quince minutos. Se renueva con el
-   *   `refresh_token` sin molestar al usuario.
-   * - Los permisos, que son una foto del momento en que se autorizó. Se vuelven
-   *   a pedir cuando se pasa `revalidate`, que es lo que hace que revocar un rol
-   *   surta efecto de inmediato en lugar de esperar a que caduque la cookie.
-   *
-   * Si el portal rechaza la credencial —token revocado, sesión cerrada, cuenta
-   * bloqueada— se devuelve `null`: la sesión terminó. Un fallo de red o un error
-   * del servidor, en cambio, se propaga: son un mal momento, no una razón para
-   * cerrar la sesión de nadie.
-   */
-  async function resolveSession(
-    cookieValue: string | undefined,
-    resolution: { revalidate?: boolean } = {},
-  ): Promise<ResolvedSession<Permission> | null> {
-    const payload = await openSession(cookieValue, resolved.secret);
-    if (!payload) return null;
-
-    const expired = payload.expiresAt * 1000 <= Date.now();
-
-    // Camino rápido: ni caducó ni se pidió frescura, así que el descifrado local
-    // basta y no se añade una ida y vuelta a cada petición.
-    if (!expired && !resolution.revalidate) {
-      return { session: sessionFromPayload<Permission>(payload), cookie: null };
-    }
-
-    let accessToken = payload.accessToken;
-    let refreshToken = payload.refreshToken;
-    let idToken = payload.idToken;
-    let expiresAt = payload.expiresAt;
-
-    // Sin refresh token no queda nada que canjear: la sesión ya no sirve ni
-    // para llamar al portal. Se decide antes de pedir el descubrimiento, para
-    // no gastar una ida y vuelta en un caso ya resuelto.
-    if (expired && !refreshToken) return null;
-
-    const discovery = await discover(resolved.issuer);
-
-    if (expired && refreshToken) {
-      try {
-        const current = refreshToken;
-        const tokens = await refreshOnce(current, () =>
-          refreshTokens({
-            discovery,
-            clientId: resolved.clientId,
-            clientSecret: resolved.clientSecret,
-            refreshToken: current,
-          }),
-        );
-
-        accessToken = tokens.accessToken;
-        refreshToken = tokens.refreshToken ?? refreshToken;
-        idToken = tokens.idToken ?? idToken;
-        expiresAt = tokens.expiresAt;
-      } catch (error: unknown) {
-        if (isCredentialRejected(error)) return null;
-        if (warnIfStaleSession(payload.expiresAt)) return null;
-        throw error;
-      }
-    }
-
-    let profile: Record<string, unknown>;
-    try {
-      profile = await fetchUserInfo({ discovery, accessToken });
-    } catch (error: unknown) {
-      if (isCredentialRejected(error)) return null;
-      if (warnIfStaleSession(payload.expiresAt)) return null;
-      throw error;
-    }
-
-    const session = buildSession<Permission>(profile, {
-      accessToken,
-      expiresAt,
-    });
-
-    const next: SessionPayload = {
-      sub: session.user.id,
-      email: session.user.email,
-      emailVerified: session.user.emailVerified,
-      name: session.user.name,
-      image: session.user.image,
-      roles: session.roles,
-      permissions: session.permissions,
-      amr: session.amr,
-      accessToken,
-      refreshToken,
-      idToken,
-      expiresAt,
-    };
-
-    return {
-      session,
-      cookie: await sealSession(next, resolved.secret, maxAge),
-    };
-  }
-
-  /**
-   * Renueva y vuelve a la aplicación.
-   *
-   * Es la única forma de persistir la renovación desde cualquier sitio: las
-   * pantallas de servidor no pueden escribir cookies, así que si el refresco
-   * ocurre ahí, el resultado se pierde al terminar la respuesta.
-   */
-  async function handleRefresh(request: Request): Promise<Response> {
-    const url = new URL(request.url);
-    const secure = originOf(request).startsWith("https://");
-    const returnTo = safeReturnTo(url.searchParams.get("to"));
-
-    let resolved: ResolvedSession<Permission> | null;
-    try {
-      resolved = await resolveSession(readCookie(request, cookieName), {
-        revalidate: true,
-      });
-    } catch {
-      // El portal no respondió. No se toca la cookie: la sesión sigue siendo la
-      // de antes y borrarla convertiría una caída en una sesión perdida.
-      return new Response("No se pudo comprobar la sesión con el portal.", {
-        status: 503,
-      });
-    }
-
-    const headers: Array<[string, string]> = [
-      ["location", `${originOf(request)}${returnTo}`],
-    ];
-
-    if (!resolved) {
-      headers.push(["set-cookie", cookieHeader(cookieName, "", 0, secure)]);
-    } else if (resolved.cookie) {
-      headers.push([
-        "set-cookie",
-        cookieHeader(cookieName, resolved.cookie, maxAge, secure),
-      ]);
-    }
-
-    return new Response(null, { status: 302, headers });
-  }
-
-  return {
-    basePath,
-    cookieName,
-    sessionMaxAge: maxAge,
-
-    signInPath(returnTo) {
-      return returnTo
-        ? `${basePath}/sign-in?to=${encodeURIComponent(returnTo)}`
-        : `${basePath}/sign-in`;
-    },
-
-    signOutPath() {
-      return `${basePath}/sign-out`;
-    },
-
-    async readSession(cookieValue) {
-      const payload = await openSession(cookieValue, resolved.secret);
-      if (!payload) return null;
-
-      return sessionFromPayload<Permission>(payload);
-    },
-
-    resolveSession,
-
-    async handleRequest(request) {
-      const { pathname } = new URL(request.url);
-      if (!pathname.startsWith(`${basePath}/`)) return null;
-
-      const route = pathname.slice(basePath.length + 1);
-      const handler =
-        route === "sign-in"
-          ? handleSignIn
-          : route === "callback"
-            ? handleCallback
-            : route === "sign-out"
-              ? handleSignOut
-              : route === "refresh"
-                ? handleRefresh
-                : null;
-      if (!handler) return null;
-
-      try {
-        return await handler(request);
-      } catch (error: unknown) {
-        // Portal caído o colgado: respuesta controlada, sin pila ni detalles hacia el navegador.
-        console.error(`[sso] ${route} falló:`, error);
-        return new Response("El portal SSO no responde. Intenta de nuevo.", {
-          status: 503,
-        });
-      }
-    },
-  };
-}
+import { resolveOptions, validateOptions } from "./config";
+import {
+  authorizationUrl,
+  buildSession,
+  discover,
+  exchangeCode,
+  fetchUserInfo,
+  refreshOnce,
+  refreshTokens,
+  sessionFromPayload,
+  type TokenSet,
+} from "./core";
+import { isCredentialRejected, SSOError } from "./errors";
+import { createAuthorizationAttempt, statesMatch } from "./pkce";
+import {
+  openSession,
+  type SessionPayload,
+  sealSession,
+} from "./session-cookie";
+import type { SSOClientOptions, SSOSession } from "./types";
+
+export {
+  type ResolvedSSOOptions,
+  resolveOptions,
+  validateOptions,
+} from "./config";
+export {
+  clearDiscoveryCache,
+  clientCredentialsToken,
+  introspectToken,
+} from "./core";
+export {
+  SSOConfigError,
+  SSOError,
+  SSOForbiddenError,
+  SSOProtocolError,
+} from "./errors";
+export {
+  type AccessPolicy,
+  authorize,
+  SSOAuthRequiredError,
+  SSOMfaRequiredError,
+} from "./policy";
+export type {
+  AuthMethod,
+  SSOClientOptions,
+  SSOSession,
+  SSOUser,
+} from "./types";
+
+/**
+ * `offline_access` va por defecto a propósito.
+ *
+ * Es lo que hace que el portal emita un `refresh_token`. Sin él, el access token
+ * dura quince minutos y no hay forma de renovarlo: la aplicación se quedaría sin
+ * acceso a las APIs a los quince minutos y solo podría recuperarlo volviendo a
+ * mandar al usuario a autenticarse.
+ */
+const DEFAULT_SCOPES = ["openid", "profile", "email", "offline_access"];
+const DEFAULT_BASE_PATH = "/api/sso";
+const DEFAULT_COOKIE = "__Host-sso_session";
+const DEFAULT_MAX_AGE = 7 * 24 * 60 * 60;
+
+/**
+ * Ventana de gracia con el portal caído.
+ *
+ * Cuando el portal no responde, la sesión se sirve de la cookie sin poder
+ * revalidar (fail-open deliberado por disponibilidad). Sin tope, una caída
+ * prolongada congelaría autorizaciones —incluidos roles ya revocados— hasta
+ * agotar la cookie. Pasada esta holgura desde que caducó el acceso, la sesión
+ * local deja de aceptarse y se pide autenticarse de nuevo.
+ */
+export const MAX_STALE_SECONDS = 60 * 60;
+
+let lastStaleWarningAt = 0;
+
+/**
+ * Si una sesión en caché superó la ventana de gracia, avisa (como mucho una
+ * vez por minuto) y pide tratarla como terminada.
+ */
+export function warnIfStaleSession(expiresAtSeconds: number): boolean {
+  if (Date.now() / 1000 - expiresAtSeconds <= MAX_STALE_SECONDS) return false;
+
+  if (Date.now() - lastStaleWarningAt > 60_000) {
+    lastStaleWarningAt = Date.now();
+    console.warn(
+      "[dacyti-auth] el portal no responde y la sesión en caché superó la ventana de gracia: se exige autenticarse de nuevo en lugar de servir permisos congelados.",
+    );
+  }
+
+  return true;
+}
+
+/**
+ * Cookie temporal donde viven el verifier y el state entre ida y vuelta. Lleva el `state` en el
+ * nombre: con una sola cookie, abrir dos pestañas a la vez haría que la segunda pisara el intento
+ * de la primera y esta fallara al volver.
+ */
+const ATTEMPT_COOKIE = "sso_attempt";
+const ATTEMPT_MAX_AGE = 10 * 60;
+const STATE_SHAPE = /^[A-Za-z0-9_-]{8,64}$/;
+const attemptCookieName = (state: string) => `${ATTEMPT_COOKIE}_${state}`;
+
+/**
+ * Los navegadores descartan sin avisar una cookie que pasa de ~4 KB, y la sesión guarda tres
+ * tokens: si algún día no cabe, el síntoma sería un bucle infinito de login. Mejor un error claro.
+ */
+const MAX_COOKIE_BYTES = 4000;
+
+export type ResolvedSession<Permission extends string = string> = {
+  session: SSOSession<Permission>;
+  /**
+   * Cookie nueva, ya sellada. `null` si nada cambió y la anterior sigue valiendo.
+   *
+   * Quien pueda escribir cookies —una Server Action, un route handler— debe
+   * guardarla; quien no pueda, al menos tiene la sesión correcta para esta
+   * respuesta.
+   */
+  cookie: string | null;
+};
+
+export type SSOClient<Permission extends string = string> = {
+  readonly basePath: string;
+  readonly cookieName: string;
+  /** Duración de la sesión local, en segundos. */
+  readonly sessionMaxAge: number;
+
+  /** URL a la que enviar a alguien para autenticarse. */
+  signInPath(returnTo?: string): string;
+  /** URL para cerrar la sesión local y la del portal. */
+  signOutPath(): string;
+
+  /** Reconstruye la sesión desde la cookie. `null` si no hay o caducó. */
+  readSession(
+    cookieValue: string | undefined,
+  ): Promise<SSOSession<Permission> | null>;
+
+  /**
+   * Sesión al día: renueva el acceso caducado y, si se pide, vuelve a consultar
+   * los permisos al portal.
+   *
+   * `readSession` es un descifrado local y no habla con el portal, así que sirve
+   * una foto que puede tener días. Esto es lo contrario: comprueba contra el
+   * portal y devuelve permisos vivos.
+   */
+  resolveSession(
+    cookieValue: string | undefined,
+    options?: { revalidate?: boolean },
+  ): Promise<ResolvedSession<Permission> | null>;
+
+  /** Atiende las rutas del cliente. Devuelve `null` si la ruta no le compete. */
+  handleRequest(request: Request): Promise<Response | null>;
+};
+
+/**
+ * Declara el cliente del portal.
+ *
+ * Sin ceremonia: lo que no se pasa se lee del entorno.
+ *
+ * ```ts
+ * export const sso = defineSSO({ permissions: ["documentos:crear", "documentos:anular"] });
+ * // issuer ← SSO_ISSUER, clientId ← SSO_CLIENT_ID,
+ * // clientSecret ← SSO_CLIENT_SECRET, secret ← SSO_SECRET
+ * ```
+ *
+ * Pasar `permissions` como tupla `as const` hace que `can()` autocomplete y que
+ * un permiso mal escrito falle al compilar, en lugar de devolver `false` en
+ * silencio en producción.
+ */
+export function defineSSO<const Permission extends string = string>(
+  options: SSOClientOptions<Permission>,
+): SSOClient<Permission> {
+  const resolved = resolveOptions(options);
+  validateOptions(resolved);
+
+  const basePath = (resolved.basePath ?? DEFAULT_BASE_PATH).replace(/\/$/, "");
+  const cookieName = resolved.cookieName ?? DEFAULT_COOKIE;
+  const scopes = resolved.scopes ?? DEFAULT_SCOPES;
+  const maxAge = resolved.sessionMaxAge ?? DEFAULT_MAX_AGE;
+
+  /**
+   * Origen público de la aplicación.
+   *
+   * Se deduce de la petición para no obligar a configurar una variable más. Se
+   * respeta `X-Forwarded-*` porque detrás de un proxy la URL de la petición
+   * lleva el host interno, y el `redirect_uri` resultante no coincidiría con el
+   * registrado.
+   */
+  function originOf(request: Request): string {
+    if (resolved.appUrl) return resolved.appUrl.replace(/\/$/, "");
+
+    const url = new URL(request.url);
+    const host = request.headers.get("x-forwarded-host") ?? url.host;
+    const protocol =
+      request.headers.get("x-forwarded-proto") ?? url.protocol.replace(":", "");
+
+    return `${protocol}://${host}`;
+  }
+
+  const redirectUriFor = (request: Request) =>
+    `${originOf(request)}${basePath}/callback`;
+
+  function readCookie(request: Request, name: string): string | undefined {
+    const header = request.headers.get("cookie");
+    if (!header) return undefined;
+
+    for (const part of header.split(";")) {
+      const trimmed = part.trim();
+      const separator = trimmed.indexOf("=");
+      if (separator > 0 && trimmed.slice(0, separator) === name) {
+        // Una cookie con `%` mal formado no debe tumbar la petición: vale como ausente.
+        try {
+          return decodeURIComponent(trimmed.slice(separator + 1));
+        } catch {
+          return undefined;
+        }
+      }
+    }
+
+    return undefined;
+  }
+
+  function cookieHeader(
+    name: string,
+    value: string,
+    seconds: number,
+    secure: boolean,
+  ): string {
+    const encoded = encodeURIComponent(value);
+    if (encoded.length > MAX_COOKIE_BYTES) {
+      throw new SSOError(
+        `La cookie ${name} pesa ${encoded.length} bytes y el navegador la descartaría (límite ~4096). ` +
+          "Reduce los permisos o scopes de la sesión.",
+      );
+    }
+
+    const attributes = [
+      `${name}=${encoded}`,
+      "Path=/",
+      "HttpOnly",
+      "SameSite=Lax",
+      `Max-Age=${seconds}`,
+    ];
+
+    // `__Host-` exige `Secure` y `Path=/` sin `Domain`: el navegador la
+    // rechaza sin aviso si falta. Se fuerza siempre.
+    if (secure || name.startsWith("__Host-")) attributes.push("Secure");
+
+    return attributes.join("; ");
+  }
+
+  /** El destino tras autenticarse solo puede ser una ruta de esta aplicación. */
+  function safeReturnTo(value: string | null): string {
+    if (!value) return "/";
+    if (!value.startsWith("/")) return "/";
+    if (value.startsWith("//")) return "/";
+    if (value.includes("\\")) return "/";
+
+    return value;
+  }
+
+  async function handleSignIn(request: Request): Promise<Response> {
+    const discovery = await discover(resolved.issuer);
+    const attempt = createAuthorizationAttempt();
+    const returnTo = safeReturnTo(new URL(request.url).searchParams.get("to"));
+
+    const target = authorizationUrl({
+      discovery,
+      clientId: resolved.clientId,
+      redirectUri: redirectUriFor(request),
+      scopes,
+      challenge: attempt.challenge,
+      state: attempt.state,
+    });
+
+    const secure = originOf(request).startsWith("https://");
+    const attemptValue = JSON.stringify({
+      verifier: attempt.verifier,
+      state: attempt.state,
+      returnTo,
+    });
+
+    return new Response(null, {
+      status: 302,
+      headers: {
+        location: target,
+        "set-cookie": cookieHeader(
+          attemptCookieName(attempt.state),
+          attemptValue,
+          ATTEMPT_MAX_AGE,
+          secure,
+        ),
+      },
+    });
+  }
+
+  async function handleCallback(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    const code = url.searchParams.get("code");
+    const state = url.searchParams.get("state");
+
+    // El `state` forma parte del nombre de la cookie: se valida su forma antes de usarlo.
+    const stateOk = state !== null && STATE_SHAPE.test(state);
+    const raw = stateOk
+      ? readCookie(request, attemptCookieName(state))
+      : undefined;
+    const secure = originOf(request).startsWith("https://");
+    const clearAttempt = stateOk
+      ? cookieHeader(attemptCookieName(state), "", 0, secure)
+      : null;
+
+    // La persona canceló o el portal rechazó la autorización (`access_denied`, etc.).
+    if (url.searchParams.get("error")) {
+      return new Response(
+        "El portal no autorizó el ingreso. Vuelve a intentarlo.",
+        {
+          status: 403,
+          headers: clearAttempt ? { "set-cookie": clearAttempt } : undefined,
+        },
+      );
+    }
+
+    /**
+     * La cookie del intento la escribió esta aplicación, pero viaja por el
+     * navegador: puede llegar truncada, editada o de una versión anterior del
+     * SDK. Sin este `try`, un `JSON.parse` sobre basura subía como error de
+     * servidor donde lo que corresponde es decir que el intento no vale.
+     */
+    let attempt: { verifier: string; state: string; returnTo: string } | null =
+      null;
+    try {
+      attempt = raw
+        ? (JSON.parse(raw) as {
+            verifier: string;
+            state: string;
+            returnTo: string;
+          })
+        : null;
+    } catch {
+      attempt = null;
+    }
+
+    /**
+     * Sin intento guardado, o con un `state` que no coincide, se aborta.
+     *
+     * Esa comprobación es lo que impide que un tercero fuerce a alguien a
+     * completar un flujo que empezó él: sin ella, un atacante puede hacer que
+     * la víctima acabe con la sesión del atacante iniciada en su navegador.
+     */
+    if (!code || !state || !attempt || !statesMatch(attempt.state, state)) {
+      return new Response("Petición de autenticación inválida o caducada.", {
+        status: 400,
+      });
+    }
+
+    let tokens: TokenSet;
+    let session: SSOSession<Permission>;
+    try {
+      const discovery = await discover(resolved.issuer);
+
+      tokens = await exchangeCode({
+        discovery,
+        clientId: resolved.clientId,
+        clientSecret: resolved.clientSecret,
+        code,
+        verifier: attempt.verifier,
+        redirectUri: redirectUriFor(request),
+      });
+
+      const profile = await fetchUserInfo({
+        discovery,
+        accessToken: tokens.accessToken,
+      });
+      session = buildSession<Permission>(profile, tokens);
+    } catch (error: unknown) {
+      // Código ya usado, caducado o portal caído: el intento no se puede reanudar, pero tampoco
+      // debe llegar al navegador un 500 con el detalle del portal.
+      console.error("[sso] el canje del código falló:", error);
+      return new Response(
+        "No se pudo completar el ingreso con el portal. Vuelve a intentarlo.",
+        {
+          status: 502,
+          headers: clearAttempt ? { "set-cookie": clearAttempt } : undefined,
+        },
+      );
+    }
+
+    const payload: SessionPayload = {
+      sub: session.user.id,
+      email: session.user.email,
+      name: session.user.name,
+      roles: session.roles,
+      permissions: session.permissions,
+      amr: session.amr,
+      accessToken: session.accessToken,
+      refreshToken: tokens.refreshToken,
+      // Se guarda porque `end-session` lo exige para cerrar la sesión del portal.
+      idToken: tokens.idToken,
+      expiresAt: session.expiresAt,
+    };
+
+    return new Response(null, {
+      status: 302,
+      headers: [
+        ["location", `${originOf(request)}${safeReturnTo(attempt.returnTo)}`],
+        [
+          "set-cookie",
+          cookieHeader(
+            cookieName,
+            await sealSession(payload, resolved.secret, maxAge),
+            maxAge,
+            secure,
+          ),
+        ],
+        // El intento ya se consumió: dejarlo vivo permitiría reutilizarlo.
+        ["set-cookie", cookieHeader(attemptCookieName(state), "", 0, secure)],
+      ],
+    });
+  }
+
+  /**
+   * Cierre de sesión en la aplicación **y** en el portal.
+   *
+   * Antes se redirigía a `end_session` sin parámetros, y el portal los exige:
+   * responde con un error de validación, así que la cookie local se borraba y
+   * la sesión del portal seguía viva. El efecto era el peor posible: el usuario
+   * creía haber salido y el siguiente «Entrar» lo dejaba dentro sin pedir nada.
+   *
+   * `id_token_hint` es lo que identifica qué sesión terminar, así que se lee de
+   * la cookie antes de borrarla. Sin él, `end-session` no tiene forma de saber
+   * de quién es la sesión y no se le puede pedir que la cierre.
+   */
+  async function handleSignOut(request: Request): Promise<Response> {
+    const origin = originOf(request);
+    const secure = origin.startsWith("https://");
+
+    const payload = await openSession(
+      readCookie(request, cookieName),
+      resolved.secret,
+    );
+
+    // Sin sesión local no hay nada que cerrar en el portal, así que ni se le
+    // pregunta: salir de una sesión que no existe no necesita una ida y vuelta.
+    let location = origin;
+
+    if (payload?.idToken) {
+      const discovery = await discover(resolved.issuer);
+
+      if (discovery.end_session_endpoint) {
+        const target = new URL(discovery.end_session_endpoint);
+        target.searchParams.set("id_token_hint", payload.idToken);
+        target.searchParams.set("client_id", resolved.clientId);
+
+        /**
+         * Solo se pide volver a la aplicación si se declaró una URI registrada.
+         * El portal rechaza cualquier destino que no lo esté, así que mandarlo
+         * a ciegas cambiaría una salida limpia por una pantalla de error.
+         */
+        if (resolved.postLogoutRedirectUri) {
+          target.searchParams.set(
+            "post_logout_redirect_uri",
+            resolved.postLogoutRedirectUri,
+          );
+        }
+
+        location = target.toString();
+      }
+    }
+
+    return new Response(null, {
+      status: 302,
+      headers: {
+        location,
+        "set-cookie": cookieHeader(cookieName, "", 0, secure),
+      },
+    });
+  }
+
+  /**
+   * Devuelve la sesión al día, hablando con el portal solo cuando hace falta.
+   *
+   * Dos cosas distintas pueden estar rancias:
+   *
+   * - El `access_token`, que dura quince minutos. Se renueva con el
+   *   `refresh_token` sin molestar al usuario.
+   * - Los permisos, que son una foto del momento en que se autorizó. Se vuelven
+   *   a pedir cuando se pasa `revalidate`, que es lo que hace que revocar un rol
+   *   surta efecto de inmediato en lugar de esperar a que caduque la cookie.
+   *
+   * Si el portal rechaza la credencial —token revocado, sesión cerrada, cuenta
+   * bloqueada— se devuelve `null`: la sesión terminó. Un fallo de red o un error
+   * del servidor, en cambio, se propaga: son un mal momento, no una razón para
+   * cerrar la sesión de nadie.
+   */
+  async function resolveSession(
+    cookieValue: string | undefined,
+    resolution: { revalidate?: boolean } = {},
+  ): Promise<ResolvedSession<Permission> | null> {
+    const payload = await openSession(cookieValue, resolved.secret);
+    if (!payload) return null;
+
+    const expired = payload.expiresAt * 1000 <= Date.now();
+
+    // Camino rápido: ni caducó ni se pidió frescura, así que el descifrado local
+    // basta y no se añade una ida y vuelta a cada petición.
+    if (!expired && !resolution.revalidate) {
+      return { session: sessionFromPayload<Permission>(payload), cookie: null };
+    }
+
+    let accessToken = payload.accessToken;
+    let refreshToken = payload.refreshToken;
+    let idToken = payload.idToken;
+    let expiresAt = payload.expiresAt;
+
+    // Sin refresh token no queda nada que canjear: la sesión ya no sirve ni
+    // para llamar al portal. Se decide antes de pedir el descubrimiento, para
+    // no gastar una ida y vuelta en un caso ya resuelto.
+    if (expired && !refreshToken) return null;
+
+    const discovery = await discover(resolved.issuer);
+
+    if (expired && refreshToken) {
+      try {
+        const current = refreshToken;
+        const tokens = await refreshOnce(current, () =>
+          refreshTokens({
+            discovery,
+            clientId: resolved.clientId,
+            clientSecret: resolved.clientSecret,
+            refreshToken: current,
+          }),
+        );
+
+        accessToken = tokens.accessToken;
+        refreshToken = tokens.refreshToken ?? refreshToken;
+        idToken = tokens.idToken ?? idToken;
+        expiresAt = tokens.expiresAt;
+      } catch (error: unknown) {
+        if (isCredentialRejected(error)) return null;
+        if (warnIfStaleSession(payload.expiresAt)) return null;
+        throw error;
+      }
+    }
+
+    let profile: Record<string, unknown>;
+    try {
+      profile = await fetchUserInfo({ discovery, accessToken });
+    } catch (error: unknown) {
+      if (isCredentialRejected(error)) return null;
+      if (warnIfStaleSession(payload.expiresAt)) return null;
+      throw error;
+    }
+
+    const session = buildSession<Permission>(profile, {
+      accessToken,
+      expiresAt,
+    });
+
+    const next: SessionPayload = {
+      sub: session.user.id,
+      email: session.user.email,
+      name: session.user.name,
+      roles: session.roles,
+      permissions: session.permissions,
+      amr: session.amr,
+      accessToken,
+      refreshToken,
+      idToken,
+      expiresAt,
+    };
+
+    return {
+      session,
+      cookie: await sealSession(next, resolved.secret, maxAge),
+    };
+  }
+
+  /**
+   * Renueva y vuelve a la aplicación.
+   *
+   * Es la única forma de persistir la renovación desde cualquier sitio: las
+   * pantallas de servidor no pueden escribir cookies, así que si el refresco
+   * ocurre ahí, el resultado se pierde al terminar la respuesta.
+   */
+  async function handleRefresh(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    const secure = originOf(request).startsWith("https://");
+    const returnTo = safeReturnTo(url.searchParams.get("to"));
+
+    let resolved: ResolvedSession<Permission> | null;
+    try {
+      resolved = await resolveSession(readCookie(request, cookieName), {
+        revalidate: true,
+      });
+    } catch {
+      // El portal no respondió. No se toca la cookie: la sesión sigue siendo la
+      // de antes y borrarla convertiría una caída en una sesión perdida.
+      return new Response("No se pudo comprobar la sesión con el portal.", {
+        status: 503,
+      });
+    }
+
+    const headers: Array<[string, string]> = [
+      ["location", `${originOf(request)}${returnTo}`],
+    ];
+
+    if (!resolved) {
+      headers.push(["set-cookie", cookieHeader(cookieName, "", 0, secure)]);
+    } else if (resolved.cookie) {
+      headers.push([
+        "set-cookie",
+        cookieHeader(cookieName, resolved.cookie, maxAge, secure),
+      ]);
+    }
+
+    return new Response(null, { status: 302, headers });
+  }
+
+  return {
+    basePath,
+    cookieName,
+    sessionMaxAge: maxAge,
+
+    signInPath(returnTo) {
+      return returnTo
+        ? `${basePath}/sign-in?to=${encodeURIComponent(returnTo)}`
+        : `${basePath}/sign-in`;
+    },
+
+    signOutPath() {
+      return `${basePath}/sign-out`;
+    },
+
+    async readSession(cookieValue) {
+      const payload = await openSession(cookieValue, resolved.secret);
+      if (!payload) return null;
+
+      return sessionFromPayload<Permission>(payload);
+    },
+
+    resolveSession,
+
+    async handleRequest(request) {
+      const { pathname } = new URL(request.url);
+      if (!pathname.startsWith(`${basePath}/`)) return null;
+
+      const route = pathname.slice(basePath.length + 1);
+      const handler =
+        route === "sign-in"
+          ? handleSignIn
+          : route === "callback"
+            ? handleCallback
+            : route === "sign-out"
+              ? handleSignOut
+              : route === "refresh"
+                ? handleRefresh
+                : null;
+      if (!handler) return null;
+
+      try {
+        return await handler(request);
+      } catch (error: unknown) {
+        // Portal caído o colgado: respuesta controlada, sin pila ni detalles hacia el navegador.
+        console.error(`[sso] ${route} falló:`, error);
+        return new Response("El portal SSO no responde. Intenta de nuevo.", {
+          status: 503,
+        });
+      }
+    },
+  };
+}