@dacyti-gsi/auth 0.0.0-stage → 0.3.0

package/src/session-cookie.ts

@@ -0,0 +1,84 @@
+import { createHash } from "node:crypto";
+
+import { EncryptJWT, jwtDecrypt } from "jose";
+
+import { SSOConfigError } from "./errors";
+
+/** Contenido que se guarda cifrado en la cookie: identidad mínima + autorización. */
+export type SessionPayload = {
+  sub: string;
+  email: string;
+  name: string | null;
+  roles: string[];
+  permissions: string[];
+  amr: string[];
+  accessToken: string;
+  refreshToken?: string;
+  /**
+   * El `id_token` de la sesión.
+   *
+   * Se guarda porque el cierre de sesión del portal lo exige: `end-session`
+   * necesita `id_token_hint` para saber qué sesión terminar, y sin él responde
+   * con un error y la sesión del portal sigue viva.
+   */
+  idToken?: string;
+  expiresAt: number;
+};
+
+/**
+ * Deriva la clave de cifrado a partir del secreto configurado.
+ *
+ * AES-256-GCM necesita exactamente 32 bytes, y un secreto escrito por una
+ * persona casi nunca los mide. Se pasa por SHA-256 para obtenerlos sin
+ * obligar a nadie a generar una clave con el tamaño justo.
+ */
+function deriveKey(secret: string): Uint8Array {
+  if (secret.length < 32) {
+    throw new SSOConfigError(
+      "`secret` necesita al menos 32 caracteres. Genera uno con:\n" +
+        "  node -e \"console.log(require('crypto').randomBytes(32).toString('base64url'))\"",
+    );
+  }
+
+  return new Uint8Array(createHash("sha256").update(secret).digest());
+}
+
+/**
+ * Cifra la sesión para guardarla en una cookie.
+ *
+ * Se cifra y no solo se firma porque el contenido incluye el access token. Una
+ * cookie firmada es legible por cualquiera que la tenga delante: un volcado de
+ * memoria, un log de proxy mal configurado o una copia del perfil del
+ * navegador bastarían para llevárselo.
+ */
+export async function sealSession(
+  payload: SessionPayload,
+  secret: string,
+  maxAgeSeconds: number,
+): Promise<string> {
+  return new EncryptJWT({ ...payload })
+    .setProtectedHeader({ alg: "dir", enc: "A256GCM" })
+    .setIssuedAt()
+    .setExpirationTime(`${maxAgeSeconds}s`)
+    .encrypt(deriveKey(secret));
+}
+
+/**
+ * Descifra la cookie. Devuelve `null` si está corrupta, caducada o cifrada con
+ * otro secreto, en lugar de lanzar: para quien llama, todos esos casos
+ * significan lo mismo —no hay sesión utilizable— y tratarlos por separado solo
+ * añadiría ramas sin ninguna decisión distinta detrás.
+ */
+export async function openSession(
+  token: string | undefined,
+  secret: string,
+): Promise<SessionPayload | null> {
+  if (!token) return null;
+
+  try {
+    const { payload } = await jwtDecrypt(token, deriveKey(secret));
+    return payload as unknown as SessionPayload;
+  } catch {
+    return null;
+  }
+}

package/src/types.ts

@@ -0,0 +1,141 @@
+/**
+ * Configuración del cliente.
+ *
+ * Todo tiene valor por defecto: lo que no se pasa se lee del entorno
+ * (`SSO_ISSUER`, `SSO_CLIENT_ID`, `SSO_CLIENT_SECRET`, `SSO_SECRET`,
+ * `APP_URL`, `SSO_POST_LOGOUT_URI`). Cada opción que hay que rellenar para
+ * empezar es una decisión que se le pide a alguien que todavía no conoce el
+ * sistema; las variables de entorno ya son el idioma de despliegue.
+ *
+ * ```ts
+ * export const sso = defineNextSSO({ permissions: ["documentos:anular"] });
+ * ```
+ */
+export type SSOClientOptions<Permission extends string = string> = {
+  /**
+   * URL del emisor, tal cual la publica el portal. Ej: `https://sso.ejemplo.com/api/auth`.
+   * Por defecto `SSO_ISSUER`.
+   */
+  issuer?: string;
+  /** Por defecto `SSO_CLIENT_ID`. */
+  clientId?: string;
+  /** Por defecto `SSO_CLIENT_SECRET`. */
+  clientSecret?: string;
+
+  /**
+   * Clave para cifrar la cookie de sesión. Mínimo 32 caracteres.
+   * Por defecto `SSO_SECRET`.
+   *
+   * La cookie guarda el access token. Cifrarla evita que acabe legible en un
+   * volcado de memoria, en un log de proxy o en una copia de seguridad del
+   * navegador.
+   */
+  secret?: string;
+
+  /**
+   * Espejo del catálogo que el portal declara para esta aplicación.
+   *
+   * El portal define los permisos (cadenas opacas: las almacena, las agrupa en
+   * roles y las emite como claim) y la aplicación les da significado al
+   * exigirlos con `can()`, `protectPage()`, `action()` o `<Protect>`. Esta
+   * lista no declara nada: si se pasa como tupla `as const`, `can()`
+   * autocompleta y un permiso mal escrito es un error de compilación en lugar
+   * de un `false` silencioso en producción.
+   *
+   * Declara primero en la consola del portal; lo que llegue sin declarar,
+   * simplemente nunca aparece en la sesión.
+   */
+  permissions?: readonly Permission[];
+
+  /** Ruta donde se montan los handlers. Por defecto `/api/sso`. */
+  basePath?: string;
+
+  /**
+   * URL pública de la aplicación consumidora. Solo explícita, nunca del
+   * entorno: el `redirect_uri` debe coincidir EXACTAMENTE con el registrado en
+   * el portal, y adivinarlo desde una variable global es como se acaba
+   * enviando el puerto equivocado.
+   *
+   * Opcional: se deduce de la petición entrante. Indícala si la aplicación vive
+   * detrás de un proxy que no reescribe `X-Forwarded-Host`, o si necesitas
+   * construir enlaces fuera del ciclo de una petición.
+   */
+  appUrl?: string;
+
+  /**
+   * A dónde vuelve el navegador tras cerrar la sesión en el portal.
+   * Por defecto `SSO_POST_LOGOUT_URI`.
+   *
+   * Por defecto, la raíz de la aplicación. **Tiene que estar registrada en el
+   * portal como URI de cierre de sesión** y coincidir exactamente: el endpoint
+   * de cierre solo redirige a URIs que un administrador dio de alta.
+   */
+  postLogoutRedirectUri?: string;
+
+  /** Por defecto `["openid", "profile", "email"]`. */
+  scopes?: string[];
+
+  /** Nombre de la cookie de sesión. Por defecto `__Host-sso_session`. */
+  cookieName?: string;
+
+  /** Duración de la sesión local, en segundos. Por defecto 7 días. */
+  sessionMaxAge?: number;
+};
+
+/** Métodos de autenticación, con los valores del RFC 8176. */
+export type AuthMethod = "pwd" | "otp" | "swk" | "mfa" | (string & {});
+
+export type SSOUser = {
+  /** Identificador estable. Úsalo como clave, no el correo. */
+  id: string;
+  email: string;
+  name: string | null;
+};
+
+export type SSOSession<Permission extends string = string> = {
+  user: SSOUser;
+
+  roles: string[];
+  permissions: Permission[];
+
+  /** Con qué se autenticó esta sesión. */
+  amr: AuthMethod[];
+
+  accessToken: string;
+  /** Marca de tiempo Unix en la que caduca el acceso. */
+  expiresAt: number;
+
+  /**
+   * Si el `access_token` ya caducó.
+   *
+   * Dura 15 minutos, muy poco frente a la vida de la cookie. Llamar a una API
+   * con un token caducado da 401, así que conviene consultarlo antes —o dejar
+   * que `session({ revalidate: true })` o `action()` lo renueven.
+   */
+  isExpired(): boolean;
+
+  /** Si la sesión tiene el permiso indicado. */
+  can(permission: Permission): boolean;
+  /** Si los tiene todos. */
+  canAll(...permissions: Permission[]): boolean;
+  /** Si tiene al menos uno. */
+  canAny(...permissions: Permission[]): boolean;
+
+  /** Lanza `SSOForbiddenError` si falta el permiso. */
+  requires(permission: Permission): void;
+
+  /** Si la autenticación usó más de un factor. */
+  usedSecondFactor(): boolean;
+};
+
+/** Documento de descubrimiento OIDC, con los campos que usa el cliente. */
+export type DiscoveryDocument = {
+  issuer: string;
+  authorization_endpoint: string;
+  token_endpoint: string;
+  userinfo_endpoint: string;
+  jwks_uri: string;
+  end_session_endpoint?: string;
+  revocation_endpoint?: string;
+  introspection_endpoint?: string;
+};