{"id":19889544,"url":"https://github.com/tsmx/express-jwt-validator","last_synced_at":"2025-11-26T03:04:16.598Z","repository":{"id":116727388,"uuid":"483373646","full_name":"tsmx/express-jwt-validator","owner":"tsmx","description":"Simple express middleware for validating JWT bearer tokens.","archived":false,"fork":false,"pushed_at":"2024-04-24T18:32:50.000Z","size":541,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-04-24T20:18:14.527Z","etag":null,"topics":["bearer-token","express","jsonwebtoken","jwt","middleware","validation","verification"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tsmx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-04-19T18:59:57.000Z","updated_at":"2024-06-19T01:19:57.408Z","dependencies_parsed_at":null,"dependency_job_id":"c8d6a163-77c8-4485-b507-8034272c8ea4","html_url":"https://github.com/tsmx/express-jwt-validator","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsmx%2Fexpress-jwt-validator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsmx%2Fexpress-jwt-validator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsmx%2Fexpress-jwt-validator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsmx%2Fexpress-jwt-validator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tsmx","download_url":"https://codeload.github.com/tsmx/express-jwt-validator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241317601,"owners_count":19943202,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bearer-token","express","jsonwebtoken","jwt","middleware","validation","verification"],"created_at":"2024-11-12T18:10:40.936Z","updated_at":"2025-11-23T16:06:18.290Z","avatar_url":"https://github.com/tsmx.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [**@tsmx/express-jwt-validator**](https://github.com/tsmx/express-jwt-validator)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n![npm (scoped)](https://img.shields.io/npm/v/@tsmx/express-jwt-validator)\n![node-current (scoped)](https://img.shields.io/node/v/@tsmx/express-jwt-validator)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/tsmx/express-jwt-validator/git-build.yml?branch=master)](https://img.shields.io/github/actions/workflow/status/tsmx/express-jwt-validator/git-build.yml?branch=master)\n[![Coverage Status](https://coveralls.io/repos/github/tsmx/express-jwt-validator/badge.svg?branch=master)](https://coveralls.io/github/tsmx/express-jwt-validator?branch=master)\n![Snyk Vulnerabilities for GitHub Repo](https://img.shields.io/snyk/vulnerabilities/github/tsmx/express-jwt-validator)\n\n\u003e Simple express middleware for validating JWT bearer tokens. \n\nStop writing boilerplate code to protect [express](https://www.npmjs.com/package/express) routes with [JWT](https://www.npmjs.com/package/jsonwebtoken) bearer tokens in your projects.\n\nSupports optional log output using [winston](https://www.npmjs.com/package/winston), [log4js](https://www.npmjs.com/package/log4js) or any other compatible logger. For details refer to the [log configuration](#logger) section\n\n## Usage\n\n```js\nconst express = require('express');\nconst app = express();\n\nconst verifyToken = require('@tsmx/express-jwt-validator')({ \n  secret: 'YOUR_JWT_SECRET' \n});\n\napp.get('/secret', verifyToken, (req, res) =\u003e {\n  // token payload available in req.authData\n  res.send('Only accessible with a valid JWT bearer token.');\n});\n```\n\nFor further customizing please refer to the [configuration options](#configuration-options).\n\n## How it works\n\nThis module exports a middleware function for express to check a request for a valid JSON Web token authorization. The token must be provided as a bearer token in the HTTP request header according to the [RFC standard](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1).\n\nRequests with a failed JWT validation will be rejected with [HTTP status 401](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401) by default. If the validations succeeds, the verified JWT payload will be added to the request and it will be passed to the next element of the middleware chain.\n\n![verify-token-schema](https://tsmx.net/wp-content/uploads/2022/04/verify-token-schema.png)\n\n## Configuration options\n\nWhen requiring in the middleware with...\n\n```js\nconst verifyToken = require('@tsmx/express-jwt-validator')({ \n  /* configuration object */ \n});\n```\n\n...the passed configuration object supports the following properties.\n\n| Property | Description |\n|----------|-------------|\n| [secret](#secret) | The JWT validation secret |\n| [header](#header) | Custom header HTTP name |\n| [strictBearerValidation](#strictbearervalidation) | Enable/disable strict validation |\n| [rejectHttpStatus](#rejecthttpstatus) | Custom HTTP response status for failed validations |\n| [sendExpiredMessage](#sendexpiredmessage) | Enable/disable error message for expired tokens |\n| [requestAuthProp](#requestauthprop) | Custom property name to store token data in `req` |\n| [logger](#logger) | An optional logger to receive log output |\n\n### secret\n\nType: `String`\n\nDefault: `undefined`\n\nMandatory: yes\n\nThe sceret used to verify the JWT bearer token. Must be present, otherwise an exception will be thrown.\n\nExample:\n\n```js\nconst verifyToken = require('@tsmx/express-jwt-validator')({ \n  secret: 'MySecretKey-123456' \n});\n```\n\n### header\n\nType: `String`\n\nDefault: `authorization`\n\nMandatory: no\n\nCan be used if the bearer token will be supplied in another header field than `authorization` (Note: HTTP header field names are case-insensitive).\n\nExample: \n\n```js\nconst verifyToken = require('@tsmx/express-jwt-validator')({ \n  secret: 'MySecretKey-123456', \n  header: 'auth' \n});\n```\n\n### strictBearerValidation\n\nType: `Boolean`\n\nDefault: `false`\n\nMandatory: no\n\nIf set to true, the authorization header is strictly validated against the schema `Bearer \u003cJWT\u003e` (including the whitespace), like `Bearer eyJhb...`. If set to false (default), it is sufficient if the header consists of two strings separated by a whitespace whereas the second entry is considered to be the JWT.\n\nExample: \n\n```js\nconst verifyToken = require('@tsmx/express-jwt-validator')({ \n  secret: 'MySecretKey-123456', \n  strictBearerValidation: true\n});\n```\n\n### rejectHttpStatus\n\nType: `Number`\n\nDefault: `401`\n\nMandatory: no\n\nThe HTTP status to be sent back to the client if the bearer token validation fails. Defaults to 401 for `Unauthorized`, could also be set to 403 `Forbidden` for example. Please note that although any status is possible here you should use an appropriate [HTTP client error code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses).\n\nExample: \n\n```js\nconst verifyToken = require('@tsmx/express-jwt-validator')({ \n  secret: 'MySecretKey-123456',\n  rejectHttpStatus: 403 \n});\n```\n\n### sendExpiredMessage\n\nType: `Boolean`\n\nDefault: `true`\n\nMandatory: no\n\nIf set to true, the rejection response will contain a JSON body with one property `error` and value `TokenExpiredError` indicating the client that the token has expired. This can be useful to allow the client to check that the token must be refreshed.\n\nIf set to false, an expired token will be rejected without any response body.\n\nExample: \n\n```js\nconst verifyToken = require('@tsmx/express-jwt-validator')({ \n  secret: 'MySecretKey-123456', \n  sendExpiredMessage: false \n});\n```\n\n### requestAuthProp\n\nType: `String`\n\nDefault: `authData`\n\nMandatory: no\n\nThe name of the property in `req` where the JWT bearer token payload should be stored for further processing. Can be changed to any property name, please make sure it is unique and no other properties are overwritten.\n\nExample: \n\n```js\nconst verifyToken = require('@tsmx/express-jwt-validator')({ \n  secret: 'MySecretKey-123456', \n  requestAuthProp: 'tokenPayload' \n});\n```\n\nToken data would now be accessible with `req.tokenPayload` instead of `req.authData` in following middleware functions. \n\n### logger\n\nType: `Object`\n\nDefault: `undefined`\n\nMandatory: no\n\nYou can pass a [winston](https://www.npmjs.com/package/winston) or [log4js](https://www.npmjs.com/package/log4js) logger instance (or any compatible) to get log output from the middleware. Compatible means that the logger must provide `info`, `warn` and `error` functions receiving a string to be logged.\n\nNote: the package contains tests for winston and log4js.\n\nThe following events will be logged:\n\n| Event | Log level |\n|-------|-----------|\n| Rejected - No auth header present | WARN |\n| Rejected - No valid 'Bearer TOKEN' entry in auth header | WARN |\n| Rejected - Strict Bearer validation failed | WARN |\n| Rejected - Expired token was sent | WARN |\n| Rejected - Invalid token was sent (potential attack) | ERROR |\n| Passed - Valid Bearer token was sent | INFO | \n\nExample for winston:\n\n```js\nconst winston = require('winston');\n\nwinstonLogger = winston.createLogger({ /*... winston options ...*/ });\n\nconst verifyToken = require('@tsmx/express-jwt-validator')({ \n  secret: 'MySecretKey-123456', \n  logger:  winstonLogger\n});\n```\n\nExample for log4js:\n\n```js\nconst log4js = require('log4js');\n\nlog4js.configure({ /*... log4js options ...*/ });\nlog4jsLogger = log4js.getLogger();\n\nconst verifyToken = require('@tsmx/express-jwt-validator')({ \n  secret: 'MySecretKey-123456', \n  logger:  log4jsLogger\n});\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsmx%2Fexpress-jwt-validator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftsmx%2Fexpress-jwt-validator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsmx%2Fexpress-jwt-validator/lists"}