@dwtechs/toker-express 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 DWTechs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,268 @@
+
+[![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)
+
+
+- [Synopsis](#synopsis)
+- [Support](#support)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Environment variables](#environment-variables)
+- [API Reference](#api-reference)
+- [Logs](#logs)
+- [Contributors](#contributors)
+- [Stack](#stack)
+
+
+## Synopsis
+
+**[Toker-express.js](https://github.com/DWTechs/Toker-express.js)** is an open source JWT management library for Express.js to refresh and decode tokens safely.  
+It includes @dwtechs/toker library and adds Express middlewares to be used in a node.js service.
+
+- 🪶 Very lightweight
+- 🧪 Thoroughly tested
+- 🚚 Shipped as EcmaScrypt Express module
+- 📝 Written in Typescript
+
+
+## Support
+
+- node: 22
+
+This is the oldest targeted versions.  
+
+
+## Installation
+
+```bash
+$ npm i @dwtechs/toker-express
+```
+
+
+## Usage
+
+
+```javascript
+
+// @ts-check
+import * as tk from "@dwtechs/Toker-express";
+import express from "express";
+const router = express.Router();
+
+import cEntity from "../entities/consumer.js";
+import uEntity from "../entities/user.js";
+import checkToken from "../middlewares/validators/check-token.js";
+import login from "../middlewares/login.js";
+
+const add = [
+  uEntity.normalize,
+  uEntity.validate,
+  login,
+  tk.refresh,
+  cEntity.add,
+];
+
+const refresh = [
+  cEntity.validate,
+  tk.decodeAccess,
+  tk.decodeRefresh,
+  checkToken,
+  tk.refresh,
+  cEntity.update,
+];
+
+const del = [
+  checkToken,
+  tk.decodeAccess,
+  cEntity.delete,
+];
+
+// Routes
+
+// add a consumer. Log a user
+router.post("/", add);
+
+// Update a consumer with new tokens
+// Used for login and refresh tokens
+router.put("/", refresh);
+
+// delete a consumer. Used when logging out
+router.delete("/", del);
+
+
+```
+
+
+### Environment variables
+
+You can intialise the library using the following environment variables:
+ 
+```bash
+  ACCESS_TOKEN_DURATION, 
+  REFRESH_TOKEN_DURATION
+  TOKEN_SECRET,
+```
+
+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.
+
+Default values : 
+
+```javascript
+const accessDuration = isNumber(ACCESS_TOKEN_DURATION, false) ? ACCESS_TOKEN_DURATION : 600; // #10 * 60 => 10 mins
+const refreshDuration = isNumber(REFRESH_TOKEN_DURATION, false) ? REFRESH_TOKEN_DURATION : 86400; // #24 * 60 * 60 => 1 day
+```
+
+## API Reference
+
+
+```typescript
+
+/**
+ * Refreshes the JWT tokens for a user.
+ *
+ * This function generates new access and refresh tokens for a user based on the provided
+ * decoded access token or user ID in the request body. It validates the issuer (iss) and
+ * creates new tokens if the validation is successful. The new tokens are then added to the
+ * response object.
+ *
+ * @param {Request} req - The request object containing the decoded access token or user ID.
+ * @param {MyResponse} res - The response object where the new tokens will be added.
+ * @param {NextFunction} next - The next middleware function in the Express.js request-response cycle.
+ *
+ * @returns {Promise<void>} Calls the next middleware function with an error if the issuer is invalid,
+ *          otherwise proceeds to the next middleware function.
+ * 
+ * @throws {InvalidIssuerError} If the issuer (iss) is not a string or number (HTTP 400)
+ * @throws {InvalidSecretsError} If the secrets array is empty or invalid (HTTP 500)
+ * @throws {InvalidDurationError} If the duration is not a positive number (HTTP 400)
+ * @throws {InvalidBase64Secret} If the secret cannot be decoded from base64 (HTTP 500)
+ * @throws {Object} Will call next() with error object containing:
+ *   - statusCode: 400 - When iss (issuer) is missing or invalid
+ *   - statusCode: 400 - When iss is not a valid number between 1 and 999999999
+ */
+function refresh(req: Request, res: MyResponse, 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 the request object for use by subsequent
+ * middleware. It only processes requests that have `req.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 {NextFunction} next - The next middleware function to be called
+ * 
+ * @returns {void} Calls the next middleware function, either with an error or successfully
+ * 
+ * @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)
+ * @throws {ExpiredTokenError} If the token has expired (exp claim) (HTTP 401)
+ * @throws {InactiveTokenError} If the token cannot be used yet (nbf claim) (HTTP 401)
+ * @throws {InvalidSignatureError} If the token signature is invalid (HTTP 401)
+ * @throws {InvalidSecretsError} If the secrets configuration is invalid (HTTP 500)
+ * @throws {InvalidBase64Secret} If the secret cannot be decoded from base64 (HTTP 500)
+ * @throws {Object} Will call next() with error object containing:
+ *   - statusCode: 401 - When token is not a valid JWT format
+ *   - statusCode: 400 - When decoded token is missing required 'iss' claim
+ * 
+ * @example
+ * ```typescript
+ * // Usage in Express route with protection middleware
+ * const protect = (req: Request, res: Response, next: NextFunction) => {
+ *   req.isProtected = true;
+ *   next();
+ * };
+ * 
+ */
+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 {NextFunction} next - The next middleware function to be called.
+ * 
+ * @returns {Promise<void>} Calls the next middleware function with an error object if the token is invalid or missing required fields.
+ * 
+ * @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)
+ * @throws {InactiveTokenError} If the token cannot be used yet (nbf claim) (HTTP 401)
+ * @throws {InvalidSignatureError} If the token signature is invalid (HTTP 401)
+ * @throws {InvalidBase64Secret} If the secret cannot be decoded from base64 (HTTP 500)
+ * @throws {Object} Will call next() with error object containing:
+ *   - statusCode: 401 - When refresh token is not a valid JWT format
+ *   - statusCode: 400 - When decoded token is missing required 'iss' claim
+ */
+function decodeRefresh(req: Request, _res: Response, next: NextFunction): void {}
+
+```
+
+### JWT Refresh
+
+This function will look for an ISS in the client request body :
+
+```Javascript
+const iss = req.body.decodedAccessToken?.iss || req.body?.id?.toString();
+```
+
+It will then send both new refresh and access tokens in the res object.
+
+```Javascript
+res.rows = [{ accessToken, refreshToken }];
+```
+
+### JWT Decoding
+
+decodeAccess() functions will look for a bearer in authorization headers.
+
+```Javascript
+const bearer = req.headers.authorization;
+```
+
+It will then send the decoded token in the res object.
+
+```Javascript
+req.decodedAccessToken = decodedToken;
+```
+
+decodeRefresh() functions will look for a token in the client request body.
+
+```Javascript
+const token = req.body.refreshToken;
+```
+
+It will then send the decoded token in the res object.
+
+```Javascript
+req.decodedRefreshToken = decodedToken;
+```
+
+
+## Logs
+
+**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.
+
+## 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 |
+| :-------------- | :------------------------------------------: | -------------------------------------------------------------: |
+| repository      |        [Github](https://github.com/)         |     hosting for software development version control using Git |
+| package manager |     [npm](https://www.npmjs.com/get-npm)     |                                default node.js package manager |
+| language        | [TypeScript](https://www.typescriptlang.org) | static type checking along with the latest ECMAScript features |
+| module bundler  |      [Rollup](https://rollupjs.org)          |                        advanced module bundler for ES6 modules |
+| unit testing    |          [Jest](https://jestjs.io/)          |                  delightful testing with a focus on simplicity |

package/dist/toker-express.d.ts

@@ -0,0 +1,51 @@
+/*
+MIT License
+
+Copyright (c) 2025 DWTechs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+https://github.com/DWTechs/Toker-express.js
+*/
+
+import type { Request, Response, NextFunction } from 'express';
+import type { MyResponse } from './interfaces';
+
+// Extend Express Request interface globally
+declare global {
+  namespace Express {
+    interface Request {
+      isProtected?: boolean;
+      decodedAccessToken?: any;
+      decodedRefreshToken?: any;
+    }
+  }
+}
+
+declare function refresh(req: Request, res: MyResponse, next: NextFunction): Promise<void>;
+declare function decodeAccess(req: Request, _res: Response, next: NextFunction): void;
+declare function decodeRefresh(req: Request, _res: Response, next: NextFunction): Promise<void>;
+
+export { 
+  refresh,
+  decodeAccess,
+  decodeRefresh,
+};
+
+

package/dist/toker-express.js

@@ -0,0 +1,118 @@
+/*
+MIT License
+
+Copyright (c) 2025 DWTechs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+https://github.com/DWTechs/Toker-express.js
+*/
+
+import { sign, parseBearer, verify } from '@dwtechs/toker';
+import { isString, isNumber, isValidNumber, isJWT } from '@dwtechs/checkard';
+import { log } from '@dwtechs/winstan';
+
+var __awaiter = (undefined && undefined.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+const { TOKEN_SECRET, ACCESS_TOKEN_DURATION, REFRESH_TOKEN_DURATION } = process.env;
+const TE_PREFIX = "Toker-express: ";
+if (!TOKEN_SECRET)
+    throw new Error(`${TE_PREFIX} Missing TOKEN_SECRET environment variable`);
+if (!isString(TOKEN_SECRET, "!0"))
+    throw new Error(`${TE_PREFIX} Invalid TOKEN_SECRET environment variable`);
+const secrets = [TOKEN_SECRET];
+const accessDuration = isNumber(ACCESS_TOKEN_DURATION, false) ? ACCESS_TOKEN_DURATION : 600;
+const refreshDuration = isNumber(REFRESH_TOKEN_DURATION, false) ? REFRESH_TOKEN_DURATION : 86400;
+function refresh(req, res, next) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c;
+        const iss = ((_a = req.decodedAccessToken) === null || _a === void 0 ? void 0 : _a.iss) || ((_c = (_b = req.body) === null || _b === void 0 ? void 0 : _b.id) === null || _c === void 0 ? void 0 : _c.toString());
+        if (!isValidNumber(iss, 1, 999999999, false))
+            return next({ statusCode: 400, message: `${TE_PREFIX} Missing iss` });
+        log.debug(`Create tokens for user ${iss}`);
+        let accessToken;
+        let refreshToken;
+        try {
+            accessToken = sign(iss, accessDuration, "access", secrets);
+            refreshToken = sign(iss, refreshDuration, "refresh", secrets);
+        }
+        catch (err) {
+            return next(err);
+        }
+        log.debug(`refreshToken='${refreshToken}', accessToken='${accessToken}'`);
+        res.rows = [{ accessToken, refreshToken }];
+        next();
+    });
+}
+function decodeAccess(req, _res, next) {
+    log.debug(`decode access token`);
+    if (!req.isProtected)
+        return next();
+    let t;
+    try {
+        t = parseBearer(req.headers.authorization);
+    }
+    catch (e) {
+        return next(e);
+    }
+    log.debug(`accessToken : ${t}`);
+    if (!isJWT(t))
+        return next({ statusCode: 401, message: `${TE_PREFIX} Invalid access token` });
+    let decodedToken = null;
+    try {
+        decodedToken = verify(t, secrets, true);
+    }
+    catch (e) {
+        return next(e);
+    }
+    if (!isValidNumber(decodedToken.iss, 1, 999999999, false))
+        return next({ statusCode: 400, message: `${TE_PREFIX} Missing iss` });
+    log.debug(`Decoded access token : ${JSON.stringify(decodedToken)}`);
+    req.decodedAccessToken = decodedToken;
+    next();
+}
+function decodeRefresh(req, _res, next) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const token = req.body.refreshToken;
+        log.debug(`decodeRefresh(token=${token})`);
+        if (!isJWT(token))
+            return next({ statusCode: 401, message: `${TE_PREFIX} Invalid refresh token` });
+        let decodedToken = null;
+        try {
+            decodedToken = verify(token, secrets, false);
+        }
+        catch (e) {
+            return next(e);
+        }
+        if (!isValidNumber(decodedToken.iss, 1, 999999999, false))
+            return next({ statusCode: 400, message: `${TE_PREFIX} Missing iss` });
+        log.debug(`Decoded refresh token : ${JSON.stringify(req.decodedRefreshToken)}`);
+        req.decodedRefreshToken = decodedToken;
+        next();
+    });
+}
+
+export { decodeAccess, decodeRefresh, refresh };

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@dwtechs/toker-express",
+  "version": "0.1.0",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DWTechs/Toker-express.js"
+  },
+  "bugs": {
+    "url": "https://github.com/DWTechs/Toker-express.js/issues",
+    "email": ""
+  },
+  "license": "MIT",
+  "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": ""
+  },
+  "files": [
+    "dist/"
+  ],
+  "dependencies": {
+    "@dwtechs/checkard": "3.2.3",
+    "@dwtechs/toker": "0.1.0",
+    "@dwtechs/winstan": "0.3.0"
+  },
+  "devDependencies": {
+    "@types/express": "5.0.0",
+    "@rollup/plugin-node-resolve": "15.3.0",
+    "core-js": "3.38.1",
+    "rollup": "4.24.0",
+    "typescript": "5.6.3"
+  }
+}