@dwtechs/toker-express 0.3.0 → 0.4.0

package/README.md

@@ -126,7 +126,7 @@ const refreshDuration = isNumber(REFRESH_TOKEN_DURATION, false) ? REFRESH_TOKEN_
  * Express middleware to generate new access and refresh JWT tokens for a user.
  *
  * This middleware creates new access and refresh tokens based on:
- * 1. The issuer (iss) from `req.decodedAccessToken.iss` if available, OR
+ * 1. The issuer (iss) from `res.locals.decodedAccessToken.iss` if available, OR
  * 2. The user ID from `res.locals.id` if no decoded token is present
  *
  * The generated tokens are stored in:
@@ -134,9 +134,9 @@ const refreshDuration = isNumber(REFRESH_TOKEN_DURATION, false) ? REFRESH_TOKEN_
  * - `req.body.rows[0].accessToken` and `req.body.rows[0].refreshToken` (if rows array exists)
  *
  * @param {Request} req - The Express request object. May contain:
- *   - `req.decodedAccessToken.iss`: User ID from decoded access token
  *   - `req.body.rows`: Optional array where tokens will be added to first element
  * @param {Response} res - The Express response object. Should contain:
+ *   - `res.locals.decodedAccessToken.iss`: User ID from decoded access token (checked first), OR
  *   - `res.locals.id`: User ID (used if decodedAccessToken is not available)
  *   Tokens will be added to `res.locals.accessToken` and `res.locals.refreshToken`
  * @param {NextFunction} next - Express next middleware function
@@ -162,15 +162,17 @@ function refresh(req: Request, res: Response, next: NextFunction): void {}
  * Express middleware function to decode and verify an access token from the Authorization header.
  * 
  * This middleware extracts the JWT access token from the Authorization header, validates its format,
- * verifies its signature, and attaches the decoded token to req.decodedAccessToken for use by subsequent
- * middleware. It only processes requests that have `req.isProtected` set to true.
+ * verifies its signature, and attaches the decoded token to res.locals.decodedAccessToken for use by subsequent
+ * middleware. It only processes requests that have `res.locals.isProtected` set to true.
  * 
  * @param {Request} req - The Express request object containing the Authorization header
- * @param {Response} _res - The Express response object (not used in this function)
+ * @param {Response} res - The Express response object. Should contain:
+ *   - `res.locals.isProtected`: Boolean flag to determine if route requires JWT protection
+ *   Decoded token will be added to `res.locals.decodedAccessToken`
  * @param {NextFunction} next - The next middleware function to be called
  * 
- * @returns {void} Calls the next middleware function, either with an error or successfully
- * 
+ * @returns {void} Calls the next middleware function with an error object if the token is invalid or iss is missing.
+ *
  * @throws {MissingAuthorizationError} If the Authorization header is missing (HTTP 401)
  * @throws {InvalidBearerFormatError} If the Authorization header format is invalid (HTTP 401)
  * @throws {InvalidTokenError} If the token is malformed or has invalid structure (HTTP 401)
@@ -189,12 +191,12 @@ function decodeAccess(req: Request, _res: Response, next: NextFunction): void {}
 /**
  * Middleware function to decode and verify a refresh token from the request body.
  * 
- * @param {Request} req - The request object containing the refresh token in the body.
- * @param {Response} _res - The response object (not used in this function).
+ * @param {Request} req - The request object containing the refresh token in `req.body.refreshToken`
+ * @param {Response} res - The response object. Decoded token will be added to `res.locals.decodedRefreshToken`
  * @param {NextFunction} next - The next middleware function to be called.
  * 
- * @returns {void} Calls the next middleware function with an error object if the token is invalid or required fields are missing.
- * 
+ * @returns {void} Calls the next middleware function with an error object if the token is invalid or iss is missing.
+ *
  * @throws {InvalidTokenError} If the token is malformed or has invalid structure (HTTP 401)
  * @throws {InvalidSecretsError} If the secrets configuration is invalid (HTTP 500)
  * @throws {ExpiredTokenError} If the refresh token has expired (exp claim) (HTTP 401)
@@ -214,7 +216,7 @@ function decodeRefresh(req: Request, _res: Response, next: NextFunction): void {
 This function will look for an ISS (user ID) from two possible sources:
 
 ```Javascript
-let iss = req.decodedAccessToken?.iss;
+let iss = res.locals?.decodedAccessToken?.iss;
 
 if (!iss)
   iss = res.locals.id ?? null;
@@ -235,6 +237,27 @@ if (isArray(rbr, ">=", 1) && isObject(rbr[0])) {
 
 ### JWT Decoding
 
+#### Route Protection with isProtected
+
+The `decodeAccess()` middleware only processes requests when `res.locals.isProtected` is set to `true`. This allows you to selectively protect routes that require authentication.
+
+You should set this flag in a middleware before calling `decodeAccess()`:
+
+```Javascript
+// Example middleware to mark route as protected
+function protectRoute(req, res, next) {
+  res.locals.isProtected = true;
+  next();
+}
+
+// Usage
+router.get('/protected-route', protectRoute, tk.decodeAccess, yourHandler);
+```
+
+If `res.locals.isProtected` is `false`, `undefined`, or `null`, the `decodeAccess()` middleware will simply call `next()` without processing the token, allowing the request to continue to the next middleware.
+
+#### Access Token Decoding
+
 decodeAccess() functions will look for a bearer in authorization headers.
 
 ```Javascript
@@ -244,9 +267,11 @@ const bearer = req.headers.authorization;
 It will then send the decoded token in the res object.
 
 ```Javascript
-req.decodedAccessToken = decodedToken;
+res.locals.decodedAccessToken = decodedToken;
 ```
 
+#### Refresh Token Decoding
+
 decodeRefresh() functions will look for a token in the client request body.
 
 ```Javascript
@@ -256,7 +281,7 @@ const token = req.body.refreshToken;
 It will then send the decoded token in the res object.
 
 ```Javascript
-req.decodedRefreshToken = decodedToken;
+res.locals.decodedRefreshToken = decodedToken;
 ```
 
 

package/dist/toker-express.d.ts

@@ -32,19 +32,9 @@ export interface RowWithTokens {
   [key: string]: any;
 }
 
-declare global {
-  namespace Express {
-    interface Request {
-      isProtected?: boolean;
-      decodedAccessToken?: any;
-      decodedRefreshToken?: any;
-    }
-  }
-}
-
 declare function refresh(req: Request, res: Response, next: NextFunction): void;
-declare function decodeAccess(req: Request, _res: Response, next: NextFunction): void;
-declare function decodeRefresh(req: Request, _res: Response, next: NextFunction): void;
+declare function decodeAccess(req: Request, res: Response, next: NextFunction): void;
+declare function decodeRefresh(req: Request, res: Response, next: NextFunction): void;
 
 export { 
   refresh,

package/dist/toker-express.js

@@ -38,10 +38,10 @@ const secrets = [TOKEN_SECRET];
 const accessDuration = isNumber(ACCESS_TOKEN_DURATION, false) ? Number(ACCESS_TOKEN_DURATION) : 600;
 const refreshDuration = isNumber(REFRESH_TOKEN_DURATION, false) ? Number(REFRESH_TOKEN_DURATION) : 86400;
 function refresh(req, res, next) {
-    var _a, _b, _c;
-    let iss = (_a = req.decodedAccessToken) === null || _a === void 0 ? void 0 : _a.iss;
+    var _a, _b, _c, _d;
+    let iss = (_b = (_a = res.locals) === null || _a === void 0 ? void 0 : _a.decodedAccessToken) === null || _b === void 0 ? void 0 : _b.iss;
     if (!iss)
-        iss = (_b = res.locals.id) !== null && _b !== void 0 ? _b : null;
+        iss = (_c = res.locals.id) !== null && _c !== void 0 ? _c : null;
     if (!isValidNumber(iss, 1, 999999999, false))
         return next({ statusCode: 400, message: `${LOGS_PREFIX}Missing iss` });
     log.debug(`${LOGS_PREFIX}Create tokens for user ${iss}`);
@@ -57,16 +57,16 @@ function refresh(req, res, next) {
     log.debug(`refreshToken='${rt}', accessToken='${at}'`);
     res.locals.accessToken = at;
     res.locals.refreshToken = rt;
-    const rbr = (_c = req.body) === null || _c === void 0 ? void 0 : _c.rows;
+    const rbr = (_d = req.body) === null || _d === void 0 ? void 0 : _d.rows;
     if (isArray(rbr, ">=", 1) && isObject(rbr[0])) {
         rbr[0].accessToken = at;
         rbr[0].refreshToken = rt;
     }
     next();
 }
-function decodeAccess(req, _res, next) {
+function decodeAccess(req, res, next) {
     log.debug(`${LOGS_PREFIX}decode access token`);
-    if (!req.isProtected)
+    if (!res.locals.isProtected)
         return next();
     let t;
     try {
@@ -88,10 +88,10 @@ function decodeAccess(req, _res, next) {
     if (!isValidNumber(dt.iss, 1, 999999999, false))
         return next({ statusCode: 400, message: `${LOGS_PREFIX}Missing iss` });
     log.debug(`${LOGS_PREFIX}Decoded access token : ${JSON.stringify(dt)}`);
-    req.decodedAccessToken = dt;
+    res.locals.decodedAccessToken = dt;
     next();
 }
-function decodeRefresh(req, _res, next) {
+function decodeRefresh(req, res, next) {
     var _a;
     const token = (_a = req.body) === null || _a === void 0 ? void 0 : _a.refreshToken;
     log.debug(`${LOGS_PREFIX}decodeRefresh(token=${token})`);
@@ -107,7 +107,7 @@ function decodeRefresh(req, _res, next) {
     if (!isValidNumber(dt.iss, 1, 999999999, false))
         return next({ statusCode: 400, message: `${LOGS_PREFIX}Missing iss` });
     log.debug(`${LOGS_PREFIX}Decoded refresh token : ${JSON.stringify(dt)}`);
-    req.decodedRefreshToken = dt;
+    res.locals.decodedRefreshToken = dt;
     next();
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dwtechs/toker-express",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Open source JWT management library for Express.js to refresh and decode tokens safely.",
   "keywords": [
     "JWT",