{"id":16722,"library":"express-meshblu-auth","title":"Express Meshblu Authentication Middleware","description":"express-meshblu-auth is an Express.js middleware library designed to handle all authentication styles for the Meshblu IoT platform. It simplifies the process of integrating Meshblu device authentication into Express applications by supporting various methods including cookies (meshblu_auth_uuid, meshblu_auth_token), HTTP headers (using the same cookie names), Basic authentication, and Bearer tokens. The library provides middleware functions like `auth()`, `get()`, `gateway()`, `gatewayDevice()`, and `gatewayRedirect()` to retrieve, validate, and attach Meshblu credentials and device information to the request object, or enforce access control. The current stable version is 9.2.1. While there isn't a strict release cadence, the project has seen several updates within major version 9 and a jump from v8 to v9, indicating active maintenance. Its primary differentiation lies in its specific integration with the Meshblu ecosystem, offering out-of-the-box support for its authentication paradigms.","status":"active","version":"9.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/octoblu/express-meshblu-auth","tags":["javascript","meshblu","express"],"install":[{"cmd":"npm install express-meshblu-auth","lang":"bash","label":"npm"},{"cmd":"yarn add express-meshblu-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add express-meshblu-auth","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This is an Express.js middleware and requires Express to function.","package":"express","optional":false},{"reason":"Used internally for interacting with the Meshblu API; updates to this dependency caused breaking changes in past major versions.","package":"meshblu-http","optional":false}],"imports":[{"note":"The library primarily uses CommonJS default exports, which are imported as default in ESM.","wrong":"import { MeshbluAuth } from 'express-meshblu-auth';","symbol":"MeshbluAuth","correct":"import MeshbluAuth from 'express-meshblu-auth';"},{"note":"This is the documented and historically correct way to import the module in CommonJS environments.","symbol":"MeshbluAuth (CommonJS)","correct":"const MeshbluAuth = require('express-meshblu-auth');"},{"note":"Authentication methods are instance methods of the `MeshbluAuth` class, not standalone functions.","wrong":"app.use(auth());","symbol":"meshbluAuth.auth()","correct":"app.use(meshbluAuth.auth());"}],"quickstart":{"code":"const express = require('express');\nconst MeshbluAuth = require('express-meshblu-auth');\n\nconst meshbluAuth = new MeshbluAuth({\n  protocol: 'https',\n  server: 'meshblu.octoblu.com',\n  port: 443\n});\n\nconst app = express();\n\n// Retrieves the uuid & token from the request,\n// validate them, then add them to request.meshbluAuth\napp.use(meshbluAuth.auth());\n\n// Retrieves the uuid & token from the request,\n// validate them by retrieving the device, then:\n// add credentials to request.meshbluAuth\n// add device to request.meshbluDevice\napp.use(meshbluAuth.get());\n\n// Returns a 401 if no uuid & token were provided in the request\n// Returns a 403 if the uuid & token provided were invalid\n// calls next otherwise\n// meshbluAuth.auth or meshbluAuth.get MUST BE CALLED FIRST in the middleware chain\napp.use(meshbluAuth.gateway());\n\n// Returns a 401 if no uuid & token were provided in the request\n// Returns a 403 if the uuid & token provided were invalid\n// Returns a 403 if the uuid given does not match the authorized uuid\n// calls next otherwise\n// meshbluAuth.auth or meshbluAuth.get MUST BE CALLED FIRST in the middleware chain\napp.use(meshbluAuth.gatewayDevice('uuid'));\n\n// Can be used instead of gateway. Redirects user if uuid & token were not\n// provided or were not valid\napp.use(meshbluAuth.gatewayRedirect('/login'));\n\napp.use(function (request, response) {\n  response.json({uuid: request.meshbluAuth.uuid, token: request.meshbluAuth.token});\n});\n\napp.listen(3333, () => {\n  console.log('Meshblu auth example app listening on port 3333');\n});\n","lang":"javascript","description":"Demonstrates how to initialize the MeshbluAuth middleware and apply its core authentication (`auth()`), device retrieval (`get()`), and access control (`gateway()`, `gatewayDevice()`, `gatewayRedirect()`) functions to an Express application. It showcases how to access authenticated Meshblu UUID and token from the request object."},"warnings":[{"fix":"Review your configuration for `patchGlobal` and refactor to remove its usage, as it's no longer supported.","message":"Starting with version 9.0.0, the `patchGlobal` option has been removed. Configurations that relied on `patchGlobal` must be updated.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Ensure that `app.use(meshbluAuth.auth())` or `app.use(meshbluAuth.get())` appears before any `gateway()` or `gatewayDevice()` calls in your Express middleware setup.","message":"The `meshbluAuth.gateway()` and `meshbluAuth.gatewayDevice()` middleware functions explicitly require `meshbluAuth.auth()` or `meshbluAuth.get()` to be called earlier in the Express middleware chain to populate `request.meshbluAuth`.","severity":"gotcha","affected_versions":">=8.0.0"},{"fix":"Thoroughly test your application when upgrading to v8.0.0 or higher. Consult the `meshblu-http` package's release notes for potential breaking changes relevant to its API.","message":"Version 8.0.0 upgraded to the 'latest meshblu-http' package. While not explicitly detailed in the release notes for `express-meshblu-auth`, this could introduce breaking changes if the underlying `meshblu-http` library itself had API changes that impact `express-meshblu-auth`'s public interface or expected behavior.","severity":"breaking","affected_versions":">=8.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Verify that `meshbluAuth.auth()` or `meshbluAuth.get()` is correctly placed and executed in the Express middleware chain prior to any code attempting to access `request.meshbluAuth`.","cause":"Attempting to access `request.meshbluAuth.uuid` (or `token`) before the `auth()` or `get()` middleware has successfully run and populated the `request.meshbluAuth` object.","error":"TypeError: Cannot read properties of undefined (reading 'uuid')"},{"fix":"For ESM, use `import MeshbluAuth from 'express-meshblu-auth';`. For CommonJS, use `const MeshbluAuth = require('express-meshblu-auth');`.","cause":"Incorrectly importing the `MeshbluAuth` class, commonly by using named import syntax for a CommonJS default export in an ESM context (e.g., `import { MeshbluAuth } from 'express-meshblu-auth';`).","error":"TypeError: MeshbluAuth is not a constructor"},{"fix":"Ensure `meshbluAuth.gatewayDevice()` is called with a valid string representing the UUID, e.g., `app.use(meshbluAuth.gatewayDevice('your-device-uuid'));`","cause":"The `meshbluAuth.gatewayDevice()` method was called without providing a required `uuid` string argument, or the argument provided was not a string.","error":"Error: `uuid` must be a string"}],"ecosystem":"npm"}