docs: improve jwt-auth package documentation

examples/express-refresh-auth/server.cjs

@@ -0,0 +1,99 @@
+require('dotenv').config();
+
+const express = require('express');
+const cookieParser = require('cookie-parser');
+const {
+  jwt,
+  password,
+  middleware,
+  cookies,
+} = require('@devflow-modules/jwt-auth');
+
+const app = express();
+app.use(express.json());
+app.use(cookieParser());
+
+const users = new Map();
+
+async function seedUser() {
+  const passwordHash = await password.hashPassword('password123');
+
+  users.set('demo@example.com', {
+    id: 'user-123',
+    email: 'demo@example.com',
+    role: 'admin',
+    passwordHash,
+  });
+}
+
+app.post('/login', async (req, res) => {
+  const { email, password: plainPassword } = req.body;
+  const user = users.get(email);
+
+  if (!user) {
+    return res.status(401).json({ message: 'Invalid credentials.' });
+  }
+
+  const isPasswordValid = await password.comparePassword(
+    plainPassword,
+    user.passwordHash
+  );
+
+  if (!isPasswordValid) {
+    return res.status(401).json({ message: 'Invalid credentials.' });
+  }
+
+  const payload = {
+    id: user.id,
+    email: user.email,
+    role: user.role,
+  };
+
+  const accessToken = jwt.signToken(payload);
+  const refreshToken = jwt.signRefreshToken({ id: user.id });
+
+  cookies.setTokenCookie(res, accessToken);
+
+  return res.json({
+    accessToken,
+    refreshToken,
+  });
+});
+
+app.post('/refresh', (req, res) => {
+  const { refreshToken } = req.body;
+
+  if (!refreshToken) {
+    return res.status(400).json({ message: 'Refresh token is required.' });
+  }
+
+  try {
+    const decoded = jwt.verifyRefreshToken(refreshToken);
+    const accessToken = jwt.signToken({ id: decoded.id });
+
+    return res.json({ accessToken });
+  } catch {
+    return res.status(401).json({ message: 'Invalid refresh token.' });
+  }
+});
+
+app.get('/private-bearer', middleware.protectRoute, (req, res) => {
+  return res.json({
+    message: 'Bearer-token route access granted.',
+    user: req.user,
+  });
+});
+
+app.get('/private-cookie', middleware.protectRouteFromCookie, (req, res) => {
+  return res.json({
+    message: 'Cookie-based route access granted.',
+    user: req.user,
+  });
+});
+
+seedUser().then(() => {
+  app.listen(3000, () => {
+    console.log('Example API running at http://localhost:3000');
+    console.log('Demo user: demo@example.com / password123');
+  });
+});

src/index.js

@@ -1,27 +1,31 @@
-// JWT: Funções para geração e verificação de access/refresh tokens
-const { signToken } = require('./jwt/signToken');
-const { verifyToken } = require('./jwt/verifyToken');
-const { signRefreshToken } = require('./jwt/signRefreshToken');
-const { verifyRefreshToken } = require('./jwt/verifyRefreshToken');
+// JWT: access/refresh token helpers
+const { signToken } = require('./jwt/signToken.cjs');
+const { verifyToken } = require('./jwt/verifyToken.cjs');
+const { signRefreshToken } = require('./jwt/signRefreshToken.cjs');
+const { verifyRefreshToken } = require('./jwt/verifyRefreshToken.cjs');
 
-// Senhas: Hash e comparação de senhas com bcrypt
-const { hashPassword } = require('./password/hashPassword');
-const { comparePassword } = require('./password/comparePassword');
+// Password helpers
+const { hashPassword } = require('./password/hashPassword.cjs');
+const { comparePassword } = require('./password/comparePassword.cjs');
 
-// Middlewares: Proteção de rotas com verificação de token (Header ou Cookie)
-const { protectRoute } = require('./middleware/protectRoute');
-const { protectRouteFromCookie } = require('./middleware/protectRouteFromCookie');
+// Express middlewares
+const { protectRoute } = require('./middleware/protectRoute.cjs');
+const { protectRouteFromCookie } = require('./middleware/protectRouteFromCookie.cjs');
+const { protectWithRoles } = require('./middleware/protectWithRoles.cjs');
 
-// Cookies: Utilitários para manipulação de token via cookies HTTP-only
-const { setTokenCookie } = require('./cookies/setTokenCookie');
-const { getTokenFromCookie } = require('./cookies/getTokenFromCookie');
+// Cookie helpers
+const { setTokenCookie } = require('./cookies/setTokenCookie.cjs');
+const { getTokenFromCookie } = require('./cookies/getTokenFromCookie.cjs');
 
 /**
- * Exporta as funcionalidades organizadas em namespaces.
- * Isso permite importar apenas o necessário com clareza:
+ * Public package API grouped by namespace.
  *
- *   const { jwt, password, middleware } = require('@devflow-modules/jwt-auth');
- *   jwt.signToken(...), password.hashPassword(...), middleware.protectRoute(...)
+ * Example:
+ *
+ * const { jwt, password, middleware, cookies } = require('@devflow-modules/jwt-auth');
+ * jwt.signToken(...)
+ * password.hashPassword(...)
+ * middleware.protectRoute(...)
  */
 
 module.exports = {
@@ -38,6 +42,7 @@ module.exports = {
   middleware: {
     protectRoute,
     protectRouteFromCookie,
+    protectWithRoles,
   },
   cookies: {
     setTokenCookie,

src/jwt/signRefreshToken.cjs

@@ -1,5 +1,5 @@
 const jwt = require('jsonwebtoken');
-const { JWT_REFRESH_SECRET, JWT_REFRESH_EXPIRES_IN } = require('../utils/env');
+const { JWT_REFRESH_SECRET, JWT_REFRESH_EXPIRES_IN } = require('../utils/env.cjs');
 
 /**
  * Gera um Refresh Token JWT.

src/jwt/signToken.cjs

@@ -6,7 +6,7 @@ const {
   JWT_SECRET,
   JWT_EXPIRES_IN = '1h',
   JWT_PRIVATE_KEY_PATH,
-} = require('../utils/env');
+} = require('../utils/env.cjs');
 
 /**
  * Gera um Access Token JWT com suporte a algoritmos simétricos (HS256/HS512)

src/jwt/verifyRefreshToken.cjs

@@ -1,5 +1,5 @@
 const jwt = require('jsonwebtoken');
-const { JWT_REFRESH_SECRET } = require('../utils/env');
+const { JWT_REFRESH_SECRET } = require('../utils/env.cjs');
 
 /**
  * Verifica e decodifica um Refresh Token JWT.

src/jwt/verifyToken.cjs

@@ -5,7 +5,7 @@ const {
   JWT_ALGORITHM = 'HS256',
   JWT_SECRET,
   JWT_PUBLIC_KEY_PATH,
-} = require('../utils/env');
+} = require('../utils/env.cjs');
 
 /**
  * Verifica e decodifica um token JWT com suporte a algoritmos simétricos e assimétricos.
@@ -46,4 +46,4 @@ function verifyToken(token, options = {}) {
   });
 }
 
-module.exports = { verifyToken };
+module.exports = { verifyToken };

src/middleware/protectRoute.cjs

@@ -1,4 +1,4 @@
-const { verifyToken } = require('../jwt/verifyToken');
+const { verifyToken } = require('../jwt/verifyToken.cjs');
 
 /**
  * Middleware para proteger rotas autenticadas.

src/middleware/protectRouteFromCookie.cjs

@@ -1,5 +1,5 @@
-const { verifyToken } = require('../jwt/verifyToken');
-const { getTokenFromCookie } = require('../cookies/getTokenFromCookie');
+const { verifyToken } = require('../jwt/verifyToken.cjs');
+const { getTokenFromCookie } = require('../cookies/getTokenFromCookie.cjs');
 
 /**
  * Middleware para proteger rotas autenticadas usando token JWT em cookies.