Skip to content

Commit 3b11bfc

Browse files
gustavomarques00gustavomarques00
authored
docs: improve jwt-auth package documentation (#20)
* docs: improve jwt-auth package documentation * docs: add Express refresh auth example * fix: resolve CommonJS exports for Node runtime * fix: resolve internal CommonJS utility import * fix: resolve internal CommonJS verify imports * fix: resolve refresh token env import * fix: resolve refresh token verify env import * fix: resolve middleware JWT import * fix: resolve cookie middleware imports
1 parent 933abab commit 3b11bfc

9 files changed

Lines changed: 294 additions & 157 deletions

File tree

‎README.md‎

Lines changed: 164 additions & 131 deletions
Large diffs are not rendered by default.

‎examples/express-refresh-auth/server.cjs‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
require('dotenv').config();
2+
3+
const express = require('express');
4+
const cookieParser = require('cookie-parser');
5+
const {
6+
jwt,
7+
password,
8+
middleware,
9+
cookies,
10+
} = require('@devflow-modules/jwt-auth');
11+
12+
const app = express();
13+
app.use(express.json());
14+
app.use(cookieParser());
15+
16+
const users = new Map();
17+
18+
async function seedUser() {
19+
const passwordHash = await password.hashPassword('password123');
20+
21+
users.set('demo@example.com', {
22+
id: 'user-123',
23+
email: 'demo@example.com',
24+
role: 'admin',
25+
passwordHash,
26+
});
27+
}
28+
29+
app.post('/login', async (req, res) => {
30+
const { email, password: plainPassword } = req.body;
31+
const user = users.get(email);
32+
33+
if (!user) {
34+
return res.status(401).json({ message: 'Invalid credentials.' });
35+
}
36+
37+
const isPasswordValid = await password.comparePassword(
38+
plainPassword,
39+
user.passwordHash
40+
);
41+
42+
if (!isPasswordValid) {
43+
return res.status(401).json({ message: 'Invalid credentials.' });
44+
}
45+
46+
const payload = {
47+
id: user.id,
48+
email: user.email,
49+
role: user.role,
50+
};
51+
52+
const accessToken = jwt.signToken(payload);
53+
const refreshToken = jwt.signRefreshToken({ id: user.id });
54+
55+
cookies.setTokenCookie(res, accessToken);
56+
57+
return res.json({
58+
accessToken,
59+
refreshToken,
60+
});
61+
});
62+
63+
app.post('/refresh', (req, res) => {
64+
const { refreshToken } = req.body;
65+
66+
if (!refreshToken) {
67+
return res.status(400).json({ message: 'Refresh token is required.' });
68+
}
69+
70+
try {
71+
const decoded = jwt.verifyRefreshToken(refreshToken);
72+
const accessToken = jwt.signToken({ id: decoded.id });
73+
74+
return res.json({ accessToken });
75+
} catch {
76+
return res.status(401).json({ message: 'Invalid refresh token.' });
77+
}
78+
});
79+
80+
app.get('/private-bearer', middleware.protectRoute, (req, res) => {
81+
return res.json({
82+
message: 'Bearer-token route access granted.',
83+
user: req.user,
84+
});
85+
});
86+
87+
app.get('/private-cookie', middleware.protectRouteFromCookie, (req, res) => {
88+
return res.json({
89+
message: 'Cookie-based route access granted.',
90+
user: req.user,
91+
});
92+
});
93+
94+
seedUser().then(() => {
95+
app.listen(3000, () => {
96+
console.log('Example API running at http://localhost:3000');
97+
console.log('Demo user: demo@example.com / password123');
98+
});
99+
});

‎src/index.js‎

Lines changed: 23 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,31 @@
1-
// JWT: Funções para geração e verificação de access/refresh tokens
2-
const { signToken } = require('./jwt/signToken');
3-
const { verifyToken } = require('./jwt/verifyToken');
4-
const { signRefreshToken } = require('./jwt/signRefreshToken');
5-
const { verifyRefreshToken } = require('./jwt/verifyRefreshToken');
1+
// JWT: access/refresh token helpers
2+
const { signToken } = require('./jwt/signToken.cjs');
3+
const { verifyToken } = require('./jwt/verifyToken.cjs');
4+
const { signRefreshToken } = require('./jwt/signRefreshToken.cjs');
5+
const { verifyRefreshToken } = require('./jwt/verifyRefreshToken.cjs');
66

7-
// Senhas: Hash e comparação de senhas com bcrypt
8-
const { hashPassword } = require('./password/hashPassword');
9-
const { comparePassword } = require('./password/comparePassword');
7+
// Password helpers
8+
const { hashPassword } = require('./password/hashPassword.cjs');
9+
const { comparePassword } = require('./password/comparePassword.cjs');
1010

11-
// Middlewares: Proteção de rotas com verificação de token (Header ou Cookie)
12-
const { protectRoute } = require('./middleware/protectRoute');
13-
const { protectRouteFromCookie } = require('./middleware/protectRouteFromCookie');
11+
// Express middlewares
12+
const { protectRoute } = require('./middleware/protectRoute.cjs');
13+
const { protectRouteFromCookie } = require('./middleware/protectRouteFromCookie.cjs');
14+
const { protectWithRoles } = require('./middleware/protectWithRoles.cjs');
1415

15-
// Cookies: Utilitários para manipulação de token via cookies HTTP-only
16-
const { setTokenCookie } = require('./cookies/setTokenCookie');
17-
const { getTokenFromCookie } = require('./cookies/getTokenFromCookie');
16+
// Cookie helpers
17+
const { setTokenCookie } = require('./cookies/setTokenCookie.cjs');
18+
const { getTokenFromCookie } = require('./cookies/getTokenFromCookie.cjs');
1819

1920
/**
20-
* Exporta as funcionalidades organizadas em namespaces.
21-
* Isso permite importar apenas o necessário com clareza:
21+
* Public package API grouped by namespace.
2222
*
23-
* const { jwt, password, middleware } = require('@devflow-modules/jwt-auth');
24-
* jwt.signToken(...), password.hashPassword(...), middleware.protectRoute(...)
23+
* Example:
24+
*
25+
* const { jwt, password, middleware, cookies } = require('@devflow-modules/jwt-auth');
26+
* jwt.signToken(...)
27+
* password.hashPassword(...)
28+
* middleware.protectRoute(...)
2529
*/
2630

2731
module.exports = {
@@ -38,6 +42,7 @@ module.exports = {
3842
middleware: {
3943
protectRoute,
4044
protectRouteFromCookie,
45+
protectWithRoles,
4146
},
4247
cookies: {
4348
setTokenCookie,

‎src/jwt/signRefreshToken.cjs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
const jwt = require('jsonwebtoken');
2-
const { JWT_REFRESH_SECRET, JWT_REFRESH_EXPIRES_IN } = require('../utils/env');
2+
const { JWT_REFRESH_SECRET, JWT_REFRESH_EXPIRES_IN } = require('../utils/env.cjs');
33

44
/**
55
* Gera um Refresh Token JWT.

‎src/jwt/signToken.cjs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ const {
66
JWT_SECRET,
77
JWT_EXPIRES_IN = '1h',
88
JWT_PRIVATE_KEY_PATH,
9-
} = require('../utils/env');
9+
} = require('../utils/env.cjs');
1010

1111
/**
1212
* Gera um Access Token JWT com suporte a algoritmos simétricos (HS256/HS512)

‎src/jwt/verifyRefreshToken.cjs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
const jwt = require('jsonwebtoken');
2-
const { JWT_REFRESH_SECRET } = require('../utils/env');
2+
const { JWT_REFRESH_SECRET } = require('../utils/env.cjs');
33

44
/**
55
* Verifica e decodifica um Refresh Token JWT.

‎src/jwt/verifyToken.cjs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ const {
55
JWT_ALGORITHM = 'HS256',
66
JWT_SECRET,
77
JWT_PUBLIC_KEY_PATH,
8-
} = require('../utils/env');
8+
} = require('../utils/env.cjs');
99

1010
/**
1111
* Verifica e decodifica um token JWT com suporte a algoritmos simétricos e assimétricos.
@@ -46,4 +46,4 @@ function verifyToken(token, options = {}) {
4646
});
4747
}
4848

49-
module.exports = { verifyToken };
49+
module.exports = { verifyToken };

‎src/middleware/protectRoute.cjs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
const { verifyToken } = require('../jwt/verifyToken');
1+
const { verifyToken } = require('../jwt/verifyToken.cjs');
22

33
/**
44
* Middleware para proteger rotas autenticadas.

‎src/middleware/protectRouteFromCookie.cjs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
const { verifyToken } = require('../jwt/verifyToken');
2-
const { getTokenFromCookie } = require('../cookies/getTokenFromCookie');
1+
const { verifyToken } = require('../jwt/verifyToken.cjs');
2+
const { getTokenFromCookie } = require('../cookies/getTokenFromCookie.cjs');
33

44
/**
55
* Middleware para proteger rotas autenticadas usando token JWT em cookies.

0 commit comments

Comments
 (0)