@dacyti-gsi/auth 0.0.0-stage → 0.2.0

package/src/core.ts

@@ -0,0 +1,451 @@
+import { SSOForbiddenError, SSOProtocolError } from "./errors";
+import type { DiscoveryDocument, SSOSession } from "./types";
+
+/**
+ * Tope de espera por llamada al portal. Sin él, un portal colgado (no caído: colgado) deja
+ * pendiente cada render que consulte la sesión, y la app entera se congela con él.
+ */
+const PORTAL_TIMEOUT_MS = 10_000;
+
+function portalFetch(url: string, init: RequestInit = {}): Promise<Response> {
+  return fetch(url, { ...init, signal: AbortSignal.timeout(PORTAL_TIMEOUT_MS) });
+}
+
+/** Cachea el documento de descubrimiento por emisor. */
+const discoveryCache = new Map<string, Promise<DiscoveryDocument>>();
+
+/**
+ * Lee el documento de descubrimiento del emisor.
+ *
+ * Se cachea en memoria: es prácticamente inmutable y pedirlo en cada login
+ * añadiría una ida y vuelta a cada autenticación. El caché muere con el
+ * proceso, así que un despliegue basta para refrescarlo.
+ */
+export function discover(issuer: string): Promise<DiscoveryDocument> {
+  const cached = discoveryCache.get(issuer);
+  if (cached) return cached;
+
+  const pending = (async () => {
+    const url = `${issuer.replace(/\/$/, "")}/.well-known/openid-configuration`;
+    const response = await portalFetch(url);
+
+    if (!response.ok) {
+      throw new SSOProtocolError(
+        `No se pudo leer el descubrimiento OIDC en ${url} (HTTP ${response.status}). ` +
+          "Comprueba que `issuer` apunta al portal y termina en /api/auth.",
+        undefined,
+        response.status,
+      );
+    }
+
+    return (await response.json()) as DiscoveryDocument;
+  })();
+
+  // Un fallo no debe quedar cacheado: el siguiente intento tiene que reintentar.
+  pending.catch(() => discoveryCache.delete(issuer));
+  discoveryCache.set(issuer, pending);
+
+  return pending;
+}
+
+/** Solo para pruebas: vacía el caché de descubrimiento y de renovaciones. */
+export function clearDiscoveryCache(): void {
+  discoveryCache.clear();
+  refreshes.clear();
+}
+
+/**
+ * Extrae un claim del portal buscándolo por sufijo.
+ *
+ * Los claims propios llegan bajo un espacio de nombres URI
+ * (`https://sso.ejemplo.com/claims/perms`), que depende del dominio donde esté
+ * desplegado el portal. Buscarlos por sufijo evita tener que configurar ese
+ * dominio en cada aplicación, y sigue funcionando si el portal se mueve.
+ */
+function claimBySuffix<T>(
+  source: Record<string, unknown>,
+  suffix: string,
+): T | undefined {
+  for (const [key, value] of Object.entries(source)) {
+    if (key.endsWith(`/claims/${suffix}`)) return value as T;
+  }
+
+  return undefined;
+}
+
+function asStringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((entry) => typeof entry === "string")
+    : [];
+}
+
+export type UserInfo = Record<string, unknown>;
+
+/**
+ * Construye la sesión a partir de la respuesta de `/userinfo`.
+ *
+ * Los permisos vienen de ahí y no del token: el `id_token` responde a quién es
+ * la persona, no a qué puede hacer. El portal, además, solo puede acotar los
+ * permisos a la aplicación correcta en ese endpoint.
+ */
+export function buildSession<Permission extends string>(
+  profile: UserInfo,
+  tokens: { accessToken: string; expiresAt: number },
+): SSOSession<Permission> {
+  const permissions = asStringArray(
+    claimBySuffix(profile, "perms"),
+  ) as Permission[];
+  const roles = asStringArray(claimBySuffix(profile, "roles"));
+  const amr = asStringArray(profile.amr);
+
+  const has = (permission: Permission) => permissions.includes(permission);
+
+  return {
+    user: {
+      id: String(profile.sub),
+      email: String(profile.email ?? ""),
+      emailVerified: profile.email_verified === true,
+      name: typeof profile.name === "string" ? profile.name : null,
+      image: typeof profile.picture === "string" ? profile.picture : null,
+    },
+    roles,
+    permissions,
+    amr,
+    accessToken: tokens.accessToken,
+    expiresAt: tokens.expiresAt,
+    isExpired: () => tokens.expiresAt * 1000 <= Date.now(),
+
+    can: has,
+    canAll: (...wanted: Permission[]) => wanted.every(has),
+    canAny: (...wanted: Permission[]) => wanted.some(has),
+    requires(permission: Permission) {
+      if (!has(permission)) throw new SSOForbiddenError(permission);
+    },
+    usedSecondFactor: () => amr.includes("mfa"),
+  };
+}
+
+/** Reconstruye la sesión desde la cookie, sin volver a llamar al portal. */
+export function sessionFromPayload<Permission extends string>(payload: {
+  sub: string;
+  email: string;
+  emailVerified: boolean;
+  name: string | null;
+  image: string | null;
+  roles: string[];
+  permissions: string[];
+  amr: string[];
+  accessToken: string;
+  expiresAt: number;
+}): SSOSession<Permission> {
+  const permissions = payload.permissions as Permission[];
+  const has = (permission: Permission) => permissions.includes(permission);
+
+  return {
+    user: {
+      id: payload.sub,
+      email: payload.email,
+      emailVerified: payload.emailVerified,
+      name: payload.name,
+      image: payload.image,
+    },
+    roles: payload.roles,
+    permissions,
+    amr: payload.amr,
+    accessToken: payload.accessToken,
+    expiresAt: payload.expiresAt,
+    isExpired: () => payload.expiresAt * 1000 <= Date.now(),
+
+    can: has,
+    canAll: (...wanted: Permission[]) => wanted.every(has),
+    canAny: (...wanted: Permission[]) => wanted.some(has),
+    requires(permission: Permission) {
+      if (!has(permission)) throw new SSOForbiddenError(permission);
+    },
+    usedSecondFactor: () => payload.amr.includes("mfa"),
+  };
+}
+
+export type TokenSet = {
+  accessToken: string;
+  refreshToken?: string;
+  idToken?: string;
+  expiresAt: number;
+};
+
+/** Canjea el código de autorización por tokens. */
+export async function exchangeCode(input: {
+  discovery: DiscoveryDocument;
+  clientId: string;
+  clientSecret: string;
+  code: string;
+  verifier: string;
+  redirectUri: string;
+}): Promise<TokenSet> {
+  const response = await portalFetch(input.discovery.token_endpoint, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      code: input.code,
+      redirect_uri: input.redirectUri,
+      client_id: input.clientId,
+      client_secret: input.clientSecret,
+      code_verifier: input.verifier,
+    }),
+  });
+
+  const body = (await response.json()) as Record<string, unknown>;
+
+  if (!response.ok) {
+    /**
+     * `invalid_scope` casi siempre es lo mismo: la aplicación se registró sin
+     * `offline_access` y el SDK lo pide por defecto para poder renovar. Sin esta
+     * pista, el mensaje que ve quien integra es un 400 sin explicación.
+     */
+    const hint =
+      body.error === "invalid_scope"
+        ? " El cliente no tiene permitido alguno de los scopes solicitados: registra " +
+          "`offline_access` en el portal, o quítalo de `scopes` al crear el cliente SSO."
+        : "";
+
+    throw new SSOProtocolError(
+      `El portal rechazó el canje del código (HTTP ${response.status}).${hint}`,
+      body,
+      response.status,
+    );
+  }
+
+  return {
+    accessToken: String(body.access_token),
+    refreshToken:
+      typeof body.refresh_token === "string" ? body.refresh_token : undefined,
+    idToken: typeof body.id_token === "string" ? body.id_token : undefined,
+    expiresAt:
+      typeof body.expires_at === "number"
+        ? body.expires_at
+        : Math.floor(Date.now() / 1000) + Number(body.expires_in ?? 900),
+  };
+}
+
+/**
+ * Cambia el `refresh_token` por un access token nuevo.
+ *
+ * Sin esto, la sesión de la aplicación muere a los quince minutos, que es lo
+ * que dura el access token, aunque la cookie siga viva durante días: cualquier
+ * llamada a una API con `session.accessToken` empezaría a responder 401 sin que
+ * nadie hubiera cerrado sesión.
+ *
+ * Requiere que la autorización se pidiera con el scope `offline_access`, que el
+ * SDK incluye por defecto. Si el portal no emitió refresh token, no hay nada
+ * que renovar y el token caducado es el final de la sesión.
+ */
+export async function refreshTokens(input: {
+  discovery: DiscoveryDocument;
+  clientId: string;
+  clientSecret: string;
+  refreshToken: string;
+}): Promise<TokenSet> {
+  const response = await portalFetch(input.discovery.token_endpoint, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: input.refreshToken,
+      client_id: input.clientId,
+      client_secret: input.clientSecret,
+    }),
+  });
+
+  const body = (await response.json().catch(() => ({}))) as Record<
+    string,
+    unknown
+  >;
+
+  if (!response.ok) {
+    throw new SSOProtocolError(
+      `El portal rechazó la renovación del acceso (HTTP ${response.status}).`,
+      body,
+      response.status,
+    );
+  }
+
+  return {
+    accessToken: String(body.access_token),
+    refreshToken:
+      typeof body.refresh_token === "string" ? body.refresh_token : undefined,
+    idToken: typeof body.id_token === "string" ? body.id_token : undefined,
+    expiresAt:
+      typeof body.expires_at === "number"
+        ? body.expires_at
+        : Math.floor(Date.now() / 1000) + Number(body.expires_in ?? 900),
+  };
+}
+
+/** Pide el perfil y los permisos. */
+export async function fetchUserInfo(input: {
+  discovery: DiscoveryDocument;
+  accessToken: string;
+}): Promise<UserInfo> {
+  const response = await portalFetch(input.discovery.userinfo_endpoint, {
+    headers: { authorization: `Bearer ${input.accessToken}` },
+  });
+
+  if (!response.ok) {
+    throw new SSOProtocolError(
+      `El portal rechazó la petición de userinfo (HTTP ${response.status}).`,
+      undefined,
+      response.status,
+    );
+  }
+
+  return (await response.json()) as UserInfo;
+}
+
+/** Construye la URL de autorización. */
+export function authorizationUrl(input: {
+  discovery: DiscoveryDocument;
+  clientId: string;
+  redirectUri: string;
+  scopes: string[];
+  challenge: string;
+  state: string;
+}): string {
+  const url = new URL(input.discovery.authorization_endpoint);
+
+  url.searchParams.set("client_id", input.clientId);
+  url.searchParams.set("redirect_uri", input.redirectUri);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("scope", input.scopes.join(" "));
+  url.searchParams.set("state", input.state);
+  url.searchParams.set("code_challenge", input.challenge);
+  url.searchParams.set("code_challenge_method", "S256");
+
+  return url.toString();
+}
+
+/**
+ * Pide un token máquina a máquina (`client_credentials`).
+ *
+ * Sin usuario detrás: no hay `id_token` ni `refresh_token`, y los scopes de
+ * identidad (`openid`, `profile`, `email`) se rechazan. Autentica con
+ * `client_secret_post`, igual que el canje de código del SDK.
+ */
+export async function clientCredentialsToken(input: {
+  discovery: DiscoveryDocument;
+  clientId: string;
+  clientSecret: string;
+  scopes?: string[];
+}): Promise<{ accessToken: string; expiresAt: number; scope: string }> {
+  const body = new URLSearchParams({
+    grant_type: "client_credentials",
+    client_id: input.clientId,
+    client_secret: input.clientSecret,
+  });
+  if (input.scopes?.length) body.set("scope", input.scopes.join(" "));
+
+  const response = await portalFetch(input.discovery.token_endpoint, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body,
+  });
+
+  const payload = (await response.json().catch(() => ({}))) as Record<
+    string,
+    unknown
+  >;
+
+  if (!response.ok) {
+    throw new SSOProtocolError(
+      `El portal rechazó las credenciales de cliente (HTTP ${response.status}).`,
+      payload,
+      response.status,
+    );
+  }
+
+  return {
+    accessToken: String(payload.access_token),
+    expiresAt:
+      typeof payload.expires_at === "number"
+        ? payload.expires_at
+        : Math.floor(Date.now() / 1000) + Number(payload.expires_in ?? 3600),
+    scope: typeof payload.scope === "string" ? payload.scope : "",
+  };
+}
+
+/**
+ * Introspección RFC 7662: pregunta al portal si un token sigue vivo.
+ *
+ * Solo para servidores de recursos confidenciales. Para autorizar a una
+ * persona, `/userinfo` sigue siendo la respuesta: la introspección no conoce
+ * la sesión ni los permisos por aplicación.
+ */
+export async function introspectToken(input: {
+  discovery: DiscoveryDocument;
+  clientId: string;
+  clientSecret: string;
+  token: string;
+}): Promise<Record<string, unknown>> {
+  const endpoint = (input.discovery as Record<string, unknown>)
+    .introspection_endpoint as string | undefined;
+  if (!endpoint) {
+    throw new SSOProtocolError(
+      "El descubrimiento no publica `introspection_endpoint`.",
+    );
+  }
+
+  const response = await portalFetch(endpoint, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      client_id: input.clientId,
+      client_secret: input.clientSecret,
+      token: input.token,
+    }),
+  });
+
+  const raw = await response.text();
+  let body: Record<string, unknown> = {};
+  try {
+    body = raw ? (JSON.parse(raw) as Record<string, unknown>) : {};
+  } catch {
+    body = { crudo: raw.slice(0, 200) };
+  }
+
+  if (!response.ok) {
+    throw new SSOProtocolError(
+      `El portal rechazó la introspección (HTTP ${response.status}).`,
+      body,
+      response.status,
+    );
+  }
+
+  return body;
+}
+
+/**
+ * Renovaciones en curso o recién hechas, por refresh token. Con rotación, el portal solo acepta un
+ * canje por token: dos renders en paralelo (layout + página) que canjearan el mismo token harían
+ * fallar al segundo y cerrarían la sesión de alguien que no hizo nada. Se conserva el resultado un
+ * minuto para los renders que lleguen justo después con la cookie vieja (los Server Components no
+ * pueden escribir la nueva; ver `sso.proxy()`).
+ */
+const REFRESH_REUSE_MS = 60_000;
+const refreshes = new Map<string, Promise<TokenSet>>();
+
+export function refreshOnce(
+  token: string,
+  run: () => Promise<TokenSet>,
+): Promise<TokenSet> {
+  const known = refreshes.get(token);
+  if (known) return known;
+
+  const pending = run();
+  refreshes.set(token, pending);
+  pending.then(
+    () => setTimeout(() => refreshes.delete(token), REFRESH_REUSE_MS).unref?.(),
+    () => refreshes.delete(token),
+  );
+
+  return pending;
+}

package/src/errors.ts

@@ -0,0 +1,53 @@
+/** Base de todos los errores del cliente, para poder capturarlos juntos. */
+export class SSOError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = new.target.name;
+  }
+}
+
+/** La configuración no permite arrancar. Se lanza al construir el cliente. */
+export class SSOConfigError extends SSOError {}
+
+/**
+ * Falta un permiso. La lanza `session.requires()`.
+ *
+ * Es una clase propia para que una aplicación pueda distinguirla de cualquier
+ * otro fallo y responder con un 403 en lugar de con un 500.
+ */
+export class SSOForbiddenError extends SSOError {
+  constructor(readonly permission: string) {
+    super(`Falta el permiso "${permission}"`);
+  }
+}
+
+/** El portal respondió con un error, o la respuesta no era la esperada. */
+export class SSOProtocolError extends SSOError {
+  constructor(
+    message: string,
+    readonly detail?: unknown,
+    /**
+     * Código HTTP de la respuesta, cuando lo hubo.
+     *
+     * Existe para poder separar dos fracasos que se parecen y no se tratan
+     * igual: un `401` significa que la credencial ya no vale y que la sesión
+     * terminó, mientras que un `502` de un proxy es un mal momento y no debe
+     * costarle la sesión a nadie.
+     */
+    readonly status?: number,
+  ) {
+    super(message);
+  }
+}
+
+/**
+ * La credencial ya no sirve: el portal respondió `401`/`403`/`400` a un token
+ * que se creía válido. La sesión se da por terminada.
+ */
+export function isCredentialRejected(error: unknown): boolean {
+  return (
+    error instanceof SSOProtocolError &&
+    typeof error.status === "number" &&
+    (error.status === 400 || error.status === 401 || error.status === 403)
+  );
+}