@dwtechs/toker-express 0.7.1 → 0.7.3

package/README.md

@@ -2,16 +2,16 @@
 [![License: MIT](https://img.shields.io/npm/l/@dwtechs/toker-express.svg?color=brightgreen)](https://opensource.org/licenses/MIT)
 [![npm version](https://badge.fury.io/js/%40dwtechs%2Ftoker-express.svg)](https://www.npmjs.com/package/@dwtechs/toker-express)
 [![last version release date](https://img.shields.io/github/release-date/DWTechs/Toker-express.js)](https://www.npmjs.com/package/@dwtechs/toker-express)
-![Jest:coverage](https://img.shields.io/badge/Jest:coverage-94%25-brightgreen.svg)
+![Jest:coverage](https://img.shields.io/badge/Jest:coverage-92%25-brightgreen.svg)
 
 
 - [Synopsis](#synopsis)
-- [Support](#support)
 - [Installation](#installation)
 - [Usage](#usage)
 - [Environment variables](#environment-variables)
 - [API Reference](#api-reference)
 - [Logs](#logs)
+- [Support](#support)
 - [Contributors](#contributors)
 - [Stack](#stack)
 
@@ -23,17 +23,10 @@ It includes @dwtechs/toker library and adds Express middlewares to be used in a
 
 - 🪶 Very lightweight
 - 🧪 Thoroughly tested
-- 🚚 Shipped as EcmaScrypt Express module
+- 🚚 Shipped as ES2022 ECMAScript module
 - 📝 Written in Typescript
 
 
-## Support
-
-- node: 22
-
-This is the oldest targeted versions.  
-
-
 ## Installation
 
 ```bash
@@ -110,7 +103,7 @@ You can intialise the library using the following environment variables:
 These environment variables will update the default values of the lib at start up.
 So you do not need to init the library in the code.
 
-Note that **TOKEN_SECRET** is mandatory.
+Note that **TOKEN_SECRET** is mandatory and must be at least 32 characters long.
 
 Default values : 
 
@@ -187,13 +180,13 @@ function refreshTokens(req: Request, res: Response, next: NextFunction): void {}
  * 
  * This middleware extracts the JWT token from the Authorization header (Bearer scheme)
  * and stores it in `res.locals.tokens.access` for use by subsequent middleware (typically decodeAccess).
- * It only processes requests that have `res.locals.route.isProtected` set to true.
+ * It only processes requests that have `res.locals.route.isProtected` or `res.locals.route.protected` set to true.
  * For non-protected routes, it simply passes control to the next middleware.
  * 
  * @param {Request} req - The Express request object. Should contain:
  *   - `req.headers.authorization`: Authorization header with Bearer token format
  * @param {Response} res - The Express response object. Should contain:
- *   - `res.locals.route.isProtected`: Boolean flag to determine if route requires JWT protection
+ *   - `res.locals.route.isProtected` or `res.locals.route.protected`: Boolean flag to determine if route requires JWT protection
  *   Parsed token will be added to `res.locals.tokens.access`
  * @param {NextFunction} next - The next middleware function to be called
  * 
@@ -215,8 +208,8 @@ function parseBearer(req: Request, res: Response, next: NextFunction): void {}
  * This middleware validates the JWT access token from `res.locals.tokens.access`,
  * verifies its signature and structure, validates the issuer (iss) claim,
  * and stores the decoded token in `res.locals.tokens.decodedAccess` for use by 
- * subsequent middleware. It only processes requests that have `res.locals.route.isProtected` 
- * set to true. For non-protected routes, it simply passes control to the next middleware.
+ * subsequent middleware. It only processes requests that have `res.locals.route.isProtected`
+ * or `res.locals.route.protected` set to true. For non-protected routes, it simply passes control to the next middleware.
  * 
  * Note: By default, this middleware checks token expiration (exp claim) and will reject
  * expired tokens. For token refresh flows where you need to identify the user even after 
@@ -225,7 +218,7 @@ function parseBearer(req: Request, res: Response, next: NextFunction): void {}
  * 
  * @param {Request} _req - The Express request object (unused)
  * @param {Response} res - The Express response object. Should contain:
- *   - `res.locals.route.isProtected`: Boolean flag to determine if route requires JWT protection
+ *   - `res.locals.route.isProtected` or `res.locals.route.protected`: Boolean flag to determine if route requires JWT protection
  *   - `res.locals.tokens.access`: The JWT token to decode (from parseBearer middleware)
  *   - `res.locals.tokens.ignoreExpiration`: Optional boolean to skip expiration checking (default: false)
  *   Decoded token will be added to `res.locals.tokens.decodedAccess`
@@ -331,16 +324,16 @@ req.body.rows[0].refreshToken = rt;
 
 ### JWT Decoding
 
-#### Route Protection with isProtected
+#### Route Protection with isProtected / protected
 
-The `parseBearer()` and `decodeAccess()` middlewares only process requests when `res.locals.route.isProtected` is set to `true`. This allows you to selectively protect routes that require authentication.
+The `parseBearer()` and `decodeAccess()` middlewares only process requests when `res.locals.route.isProtected` or `res.locals.route.protected` is set to `true`. This allows you to selectively protect routes that require authentication.
 
-You should set this flag in a middleware before calling these functions:
+You should set one of these flags in a middleware before calling these functions:
 
 ```Javascript
 // Example middleware to mark route as protected
 function protectRoute(req, res, next) {
-  res.locals.route = { isProtected: true };
+  res.locals.route = { isProtected: true }; // or { protected: true }
   next();
 }
 
@@ -348,7 +341,7 @@ function protectRoute(req, res, next) {
 router.get('/protected-route', protectRoute, tk.parseBearer, tk.decodeAccess, yourHandler);
 ```
 
-If `res.locals.route.isProtected` is `false`, `undefined`, or `null`, these middlewares will simply call `next()` without processing the token, allowing the request to continue to the next middleware.
+If both `res.locals.route.isProtected` and `res.locals.route.protected` are `false`, `undefined`, or `null`, these middlewares will simply call `next()` without processing the token, allowing the request to continue to the next middleware.
 
 #### Access Token Processing
 
@@ -385,8 +378,6 @@ The decoded token is then stored in `res.locals.tokens.decodedAccess`:
 res.locals.tokens.decodedAccess = decodedToken;
 ```
 
-**Important:** This middleware **ignores token expiration** by design. This allows expired access tokens to be decoded, which is useful for token refresh flows where you need to identify the user even after their access token has expired.
-
 **Note:** You should use both middlewares in sequence for full access token processing, or you can use just `parseBearer()` if you only need to extract the token without decoding it.
 
 #### Refresh Token Decoding
@@ -410,13 +401,19 @@ res.locals.tokens.decodedRefresh = decodedToken;
 
 **Token-express.js** uses **[@dwtechs/Winstan](https://www.npmjs.com/package/@dwtechs/winstan)** library for logging.
 All logs are in debug mode. Meaning they should not appear in production mode.
+Log messages are passed as lazy functions (`() => string`) so string interpolation and serialization are skipped entirely when debug logging is disabled.
+
+## Support
+
+| Environment | Version |
+| :---------- | :-----: |
+| Node.js     |  >= 22  |
 
 ## Contributors
 
 **Token-express.js** is still in development and we would be glad to get all the help you can provide.
 To contribute please read **[contributor.md](https://github.com/DWTechs/Token-express.js/blob/main/contributor.md)** for detailed installation guide.
 
-
 ## Stack
 
 | Purpose         |                    Choice                    |                                                     Motivation |

package/dist/toker-express.js

@@ -34,15 +34,18 @@ if (!TOKEN_SECRET)
     throw new Error(`${LOGS_PREFIX}Missing TOKEN_SECRET environment variable`);
 if (!isString(TOKEN_SECRET, "!0"))
     throw new Error(`${LOGS_PREFIX}Invalid TOKEN_SECRET environment variable`);
+if (TOKEN_SECRET.length < 32)
+    throw new Error(`${LOGS_PREFIX}TOKEN_SECRET must be at least 32 characters`);
 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 createTokens(req, res, next) {
-    var _a, _b;
-    const iss = (_b = (_a = res.locals) === null || _a === void 0 ? void 0 : _a.user) === null || _b === void 0 ? void 0 : _b.id;
-    if (!isValidInteger(iss, 1, 999999999, false))
-        return next({ statusCode: 400, message: `${LOGS_PREFIX}Missing iss` });
-    log.debug(`${LOGS_PREFIX}Create tokens for user ${iss}`);
+    const iss = res.locals?.user?.id;
+    if (!isValidInteger(iss, 1, 999999999, false)) {
+        next({ statusCode: 400, message: `${LOGS_PREFIX}Missing iss` });
+        return;
+    }
+    log.debug(() => `${LOGS_PREFIX}Create tokens for user ${iss}`);
     let at;
     let rt;
     try {
@@ -50,19 +53,21 @@ function createTokens(req, res, next) {
         rt = sign(iss, refreshDuration, "refresh", secrets);
     }
     catch (err) {
-        return next(err);
+        next(err);
+        return;
     }
-    log.debug(`refreshToken='${rt}', accessToken='${at}'`);
+    log.debug(() => `${LOGS_PREFIX}Tokens created for user ${iss}`);
     req.body.rows[0].accessToken = at;
     req.body.rows[0].refreshToken = rt;
     next();
 }
 function refreshTokens(req, res, next) {
-    var _a, _b, _c;
-    const iss = (_c = (_b = (_a = res.locals) === null || _a === void 0 ? void 0 : _a.tokens) === null || _b === void 0 ? void 0 : _b.decodedAccess) === null || _c === void 0 ? void 0 : _c.iss;
-    if (!isValidInteger(iss, 1, 999999999, false))
-        return next({ statusCode: 400, message: `${LOGS_PREFIX}Missing iss` });
-    log.debug(`${LOGS_PREFIX}Create tokens for user ${iss}`);
+    const iss = res.locals?.tokens?.decodedAccess?.iss;
+    if (!isValidInteger(iss, 1, 999999999, false)) {
+        next({ statusCode: 400, message: `${LOGS_PREFIX}Missing iss` });
+        return;
+    }
+    log.debug(() => `${LOGS_PREFIX}Create tokens for user ${iss}`);
     let at;
     let rt;
     try {
@@ -70,65 +75,81 @@ function refreshTokens(req, res, next) {
         rt = sign(iss, refreshDuration, "refresh", secrets);
     }
     catch (err) {
-        return next(err);
+        next(err);
+        return;
     }
-    log.debug(`refreshToken='${rt}', accessToken='${at}'`);
+    log.debug(() => `${LOGS_PREFIX}Tokens refreshed for user ${iss}`);
     req.body.rows[0].accessToken = at;
     req.body.rows[0].refreshToken = rt;
     next();
 }
 function parseBearer(req, res, next) {
-    var _a, _b;
-    if (!((_b = (_a = res.locals) === null || _a === void 0 ? void 0 : _a.route) === null || _b === void 0 ? void 0 : _b.isProtected))
-        return next();
-    log.debug(`${LOGS_PREFIX}parse bearer to get access token`);
+    if (!res.locals?.route?.isProtected && !res.locals?.route?.protected) {
+        next();
+        return;
+    }
+    log.debug(() => `${LOGS_PREFIX}parse bearer to get access token`);
     try {
-        res.locals.tokens = Object.assign(Object.assign({}, res.locals.tokens), { access: parseBearer$1(req.headers.authorization) });
+        res.locals.tokens ??= {};
+        res.locals.tokens.access = parseBearer$1(req.headers.authorization);
     }
     catch (e) {
-        return next(e);
+        next(e);
+        return;
     }
     next();
 }
 function decodeAccess(_req, res, next) {
-    var _a, _b, _c, _d, _e, _f, _g;
-    log.debug(`${LOGS_PREFIX}decode access token`);
-    if (!((_b = (_a = res.locals) === null || _a === void 0 ? void 0 : _a.route) === null || _b === void 0 ? void 0 : _b.isProtected))
-        return next();
-    const t = (_d = (_c = res.locals) === null || _c === void 0 ? void 0 : _c.tokens) === null || _d === void 0 ? void 0 : _d.access;
-    const ignoreExpiration = (_g = (_f = (_e = res.locals) === null || _e === void 0 ? void 0 : _e.tokens) === null || _f === void 0 ? void 0 : _f.ignoreExpiration) !== null && _g !== void 0 ? _g : false;
-    if (!isJWT(t))
-        return next({ statusCode: 401, message: `${LOGS_PREFIX}Invalid access token` });
+    log.debug(() => `${LOGS_PREFIX}decode access token`);
+    if (!res.locals?.route?.isProtected && !res.locals?.route?.protected) {
+        next();
+        return;
+    }
+    const t = res.locals?.tokens?.access;
+    const ignoreExpiration = res.locals?.tokens?.ignoreExpiration ?? false;
+    if (!isJWT(t)) {
+        next({ statusCode: 401, message: `${LOGS_PREFIX}Invalid access token` });
+        return;
+    }
     let dt = null;
     try {
         dt = verify(t, secrets, ignoreExpiration);
     }
     catch (e) {
-        return next(e);
+        next(e);
+        return;
+    }
+    if (!isValidInteger(dt.iss, 1, 999999999, false)) {
+        next({ statusCode: 400, message: `${LOGS_PREFIX}Missing iss` });
+        return;
     }
-    if (!isValidInteger(dt.iss, 1, 999999999, false))
-        return next({ statusCode: 400, message: `${LOGS_PREFIX}Missing iss` });
-    log.debug(`${LOGS_PREFIX}Decoded access token : ${JSON.stringify(dt)}`);
-    res.locals.tokens = Object.assign(Object.assign({}, res.locals.tokens), { decodedAccess: dt });
+    log.debug(() => `${LOGS_PREFIX}Access token decoded for user ${dt.iss}`);
+    res.locals.tokens ??= {};
+    res.locals.tokens.decodedAccess = dt;
     next();
 }
 function decodeRefresh(req, res, next) {
-    var _a;
-    const t = (_a = req.body) === null || _a === void 0 ? void 0 : _a.refreshToken;
-    log.debug(`${LOGS_PREFIX}decodeRefresh(token=${t})`);
-    if (!isJWT(t))
-        return next({ statusCode: 401, message: `${LOGS_PREFIX}Invalid refresh token` });
+    const t = req.body?.refreshToken;
+    log.debug(() => `${LOGS_PREFIX}Decoding refresh token`);
+    if (!isJWT(t)) {
+        next({ statusCode: 401, message: `${LOGS_PREFIX}Invalid refresh token` });
+        return;
+    }
     let dt = null;
     try {
         dt = verify(t, secrets, false);
     }
     catch (e) {
-        return next(e);
+        next(e);
+        return;
+    }
+    if (!isValidInteger(dt.iss, 1, 999999999, false)) {
+        next({ statusCode: 400, message: `${LOGS_PREFIX}Missing iss` });
+        return;
     }
-    if (!isValidInteger(dt.iss, 1, 999999999, false))
-        return next({ statusCode: 400, message: `${LOGS_PREFIX}Missing iss` });
-    log.debug(`${LOGS_PREFIX}Decoded refresh token : ${JSON.stringify(dt)}`);
-    res.locals.tokens = Object.assign(Object.assign({}, res.locals.tokens), { decodedRefresh: dt });
+    log.debug(() => `${LOGS_PREFIX}Refresh token decoded for user ${dt.iss}`);
+    res.locals.tokens ??= {};
+    res.locals.tokens.decodedRefresh = dt;
     next();
 }
 

package/package.json

@@ -1,35 +1,41 @@
 {
   "name": "@dwtechs/toker-express",
-  "version": "0.7.1",
+  "version": "0.7.3",
+  "type": "module",
   "description": "Open source JWT management library for Express.js to refresh and decode tokens safely.",
   "keywords": [
     "JWT",
     "Express"
   ],
   "homepage": "https://github.com/DWTechs/Toker-express.js",
-  "main": "dist/toker-express",
-  "types": "dist/toker-express",
+  "main": "dist/toker-express.js",
+  "types": "dist/toker-express.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/toker-express.js",
+      "types": "./dist/toker-express.d.ts"
+    }
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/DWTechs/Toker-express.js"
   },
   "bugs": {
-    "url": "https://github.com/DWTechs/Toker-express.js/issues",
-    "email": ""
+    "url": "https://github.com/DWTechs/Toker-express.js/issues"
   },
   "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
   "author": {
     "name": "Ludovic Cluber",
     "email": "http://www.lcluber.com/contact",
     "url": "http://www.lcluber.com"
   },
-  "contributors": [],
   "scripts": {
-    "start": "",
     "prebuild": "npm install",
     "build": "node ./scripts/clear && tsc && npm run rollup && node ./scripts/copy && npm run test",
     "rollup:mjs": "rollup --config rollup.config.mjs",
-    "rollup:cjs": "rollup --config rollup.config.cjs.mjs",
     "rollup": "npm run rollup:mjs",
     "test": "jest --coverage"
   },
@@ -38,17 +44,15 @@
   ],
   "dependencies": {
     "@dwtechs/checkard": "3.6.0",
-    "@dwtechs/toker": "0.1.2",
-    "@dwtechs/winstan": "0.5.0"
+    "@dwtechs/toker": "0.2.1",
+    "@dwtechs/winstan": "0.7.0"
   },
   "devDependencies": {
     "@babel/preset-env": "7.26.0",
-    "@rollup/plugin-node-resolve": "15.3.0",
-    "@types/express": "5.0.3",
+    "@types/express": "5.0.6",
     "babel-jest": "29.7.0",
-    "core-js": "3.38.1",
     "jest": "29.7.0",
     "rollup": "4.24.0",
-    "typescript": "5.9.2"
+    "typescript": "6.0.3"
   }
 }