Utilidades JWT

Overview

Este archivo reúne las funciones de apoyo para firmar y verificar JWT en el backend. Todas usan la misma clave secreta cargada desde ../config/env.js, lo que centraliza la lógica de autenticación basada en tokens.

También expone una variante con expiración explícita por segundos. Esa variante sirve para tokens de un solo propósito, donde la vigencia depende del dominio y no de env.jwtExpiresIn.

[!NOTE] Este archivo no define endpoints HTTP. Solo ofrece funciones reutilizables de token.

How it works

flowchart TB
    Env[env config] --> SignAccess[signAccessToken]
    Env --> VerifyAccess[verifyAccessToken]
    Env --> SignScoped[signScopedToken]

    SignAccess --> JwtSign[jsonwebtoken sign]
    VerifyAccess --> JwtVerify[jsonwebtoken verify]
    SignScoped --> JwtSign

El módulo importa jsonwebtoken como jwt y la configuración env. Las funciones de firma usan jwt.sign con env.jwtSecret. La función de verificación usa jwt.verify con la misma clave. La variante signScopedToken cambia solo la expiración. No usa env.jwtExpiresIn.

Key components

{
    "title": "signAccessToken",
    "content": "Firma un payload como token de acceso usando env.jwtSecret y env.jwtExpiresIn. Devuelve el JWT generado.",
    "type": "function",
    "filePath": "services/api/src/utils/jwt.js",
    "badges": [
        "public"
    ]
}

{
    "title": "verifyAccessToken",
    "content": "Verifica un token con env.jwtSecret. Devuelve el payload decodificado o lanza un error si el token no es v\u00e1lido.",
    "type": "function",
    "filePath": "services/api/src/utils/jwt.js",
    "badges": [
        "public"
    ]
}

{
    "title": "signScopedToken",
    "content": "Firma un payload con una expiraci\u00f3n expl\u00edcita en segundos. Se usa para tokens de prop\u00f3sito concreto con vigencia controlada por dominio.",
    "type": "function",
    "filePath": "services/api/src/utils/jwt.js",
    "badges": [
        "public"
    ]
}

Data & fields

[
    {
        "name": "payload",
        "type": "object",
        "required": true,
        "description": "Contenido que se incrusta dentro del JWT al firmarlo."
    },
    {
        "name": "token",
        "type": "string",
        "required": true,
        "description": "JWT recibido para su validación con verifyAccessToken."
    },
    {
        "name": "expiresInSeconds",
        "type": "number",
        "required": true,
        "description": "Duración del token scoped, expresada en segundos."
    },
    {
        "name": "env",
        "type": "object",
        "required": true,
        "description": "Configuración importada desde ../config/env.js."
    },
    {
        "name": "env.jwtSecret",
        "type": "string",
        "required": true,
        "description": "Secreto compartido para firmar y verificar tokens."
    },
    {
        "name": "env.jwtExpiresIn",
        "type": "valor compatible con expiresIn",
        "required": true,
        "description": "Duración aplicada por defecto a los tokens de acceso."
    }
]
  • payload entra directamente a jwt.sign.
  • token entra directamente a jwt.verify.
  • expiresInSeconds solo se usa en signScopedToken.
  • env.jwtSecret se reutiliza en firma y verificación.
  • env.jwtExpiresIn solo aplica a signAccessToken.

Behaviors

  • signAccessToken — Firma un JWT con payload, env.jwtSecret y env.jwtExpiresIn. Devuelve el token firmado.
  • verifyAccessToken — Verifica un JWT con env.jwtSecret. Devuelve el contenido decodificado si el token es válido.
  • signScopedToken — Firma un JWT con payload, env.jwtSecret y expiresInSeconds. Devuelve un token con caducidad explícita.

Workflows

1. Firmar token de acceso | Llamar a signAccessToken con el payload que se desea proteger.
2. Verificar token recibido | Pasar el token a verifyAccessToken para validar firma y contenido.
3. Firmar token acotado | Usar signScopedToken cuando la expiración deba depender del dominio.

Gotchas & edge cases

[!WARNING] verifyAccessToken solo valida firma y estructura. No valida el claim purpose.

[!IMPORTANT] signScopedToken no usa env.jwtExpiresIn. La expiración depende de expiresInSeconds.

[!CAUTION] Las funciones de firma y verificación comparten env.jwtSecret. Un secreto incorrecto rompe la compatibilidad entre ambos caminos.

  • services/api/src/config/env.js — Provee env.jwtSecret y env.jwtExpiresIn.
  • jsonwebtoken — Biblioteca externa usada por jwt.sign y jwt.verify.
  • jwt.sign para generar tokens.
  • jwt.verify para validar tokens.
  • env.jwtSecret como secreto común.
  • env.jwtExpiresIn como expiración por defecto para accesos.
  • expiresInSeconds como expiración explícita para tokens scoped.

Updated