IA Cheatsheets

¡Claro que sí! Aquí tienes un “cheatsheet” completo y bien estructurado de la librería jwt-decode, optimizado para ser claro y conciso para una IA conversacional.

🔑 jwt-decode Cheatsheet Completo 🔑

jwt-decode es una librería ligera para decodificar JSON Web Tokens (JWTs) en el lado del cliente (navegador o Node.js). Es importante entender que esta librería SÓLO DECODIFICA el token; NO LO VALIDA. Esto significa que no verifica la firma, la expiración o cualquier otra afirmación de seguridad.

1. 🌟 Conceptos Clave

2. 🛠️ Configuración Inicial

  1. Instalación: 
    npm install jwt-decode
# o
yarn add jwt-decode
  2. Importación: 
    import { jwtDecode } from 'jwt-decode'; // Importación con nombre (desde v4.0.0)
// O para versiones anteriores (v3.x.x):
// import jwt_decode from 'jwt-decode';

3. 🚀 Uso Básico (jwtDecode())

La función principal es jwtDecode(), que toma un JWT como string y devuelve el objeto payload decodificado.

import { jwtDecode } from 'jwt-decode';

// Ejemplo de un JWT (SOLO PARA DEMOSTRACIÓN, NO USAR TOKENS REALES AQUÍ)
const myJwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJleHAiOjE2Nzg5NzE2MDAsInJvbGUiOiJ1c2VyIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c";

try {
  const decodedPayload = jwtDecode(myJwt);
  console.log('Payload decodificado:', decodedPayload);
  /*
  Salida esperada:
  {
    sub: "1234567890",
    name: "John Doe",
    iat: 1516239022,
    exp: 1678971600, // Unix timestamp (segundos)
    role: "user"
  }
  */

  // Acceder a propiedades específicas
  console.log('Nombre de usuario:', decodedPayload.name);
  console.log('Rol:', decodedPayload.role);

  // Convertir timestamp de expiración a Date (si existe)
  if (decodedPayload.exp) {
    const expirationDate = new Date(decodedPayload.exp * 1000); // Multiplicar por 1000 para milisegundos
    console.log('Token expira el:', expirationDate);
  }

} catch (error) {
  console.error('Error al decodificar el token:', error.message);
}

4. ❌ Manejo de Errores

jwt-decode lanzará un error si el token no es un JWT válido o está malformado. Es crucial envolver la llamada en un bloque try-catch.

import { jwtDecode } from 'jwt-decode';

const invalidJwt = "esto.no.es.un.jwt.valido";
const malformedJwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.INVALID_PAYLOAD.SIGNATURE";

try {
  jwtDecode(invalidJwt);
} catch (error) {
  console.error('Error con token inválido:', error.message); // Por ejemplo: "Invalid JWT specified"
}

try {
  jwtDecode(malformedJwt);
} catch (error) {
  console.error('Error con token malformado:', error.message); // Por ejemplo: "Invalid or malformed JWT"
}

5. 🟦 Inferencia de Tipos con TypeScript

Cuando usas jwt-decode con TypeScript, puedes inferir el tipo del payload para obtener autocompletado y seguridad de tipos.

import { jwtDecode } from 'jwt-decode';

// 1. Define la interfaz de tu Payload JWT (lo que esperas en el token)
interface MyTokenPayload {
  sub: string;
  name: string;
  iat: number;
  exp: number; // Expiración en segundos (Unix timestamp)
  role: 'admin' | 'user';
  // ... cualquier otra afirmación personalizada
}

const myJwt: string = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJleHAiOjE2Nzg5NzE2MDAsInJvbGUiOiJ1c2VyIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c";

try {
  // 2. Especifica el tipo genérico al llamar a jwtDecode
  const decodedPayload = jwtDecode<MyTokenPayload>(myJwt);

  console.log('ID de usuario:', decodedPayload.sub); // TypeScript sabe que 'sub' existe y es string
  console.log('Rol del usuario:', decodedPayload.role); // TypeScript sabe que 'role' es 'admin' | 'user'

  // Esto daría un error de TypeScript porque 'nonExistentProperty' no está en MyTokenPayload
  // console.log(decodedPayload.nonExistentProperty);

} catch (error: any) { // Es buena práctica tipar el error en el catch
  console.error('Error al decodificar el token:', error.message);
}

6. ⚠️ CONSIDERACIONES DE SEGURIDAD CRÍTICAS ⚠️

¡ESTO ES LO MÁS IMPORTANTE QUE DEBES SABER SOBRE jwt-decode!

7. 💡 Buenas Prácticas y Consejos

Este cheatsheet te proporciona una comprensión profunda de jwt-decode, sus capacidades y, lo que es más importante, sus limitaciones de seguridad para que puedas usarla de manera responsable y efectiva.