Express Meshblu Authentication Middleware

9.2.1 · active · verified Wed Apr 22

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.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'uuid')
```
cause Attempting to access `request.meshbluAuth.uuid` (or `token`) before the `auth()` or `get()` middleware has successfully run and populated the `request.meshbluAuth` object.

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`.
```
TypeError: MeshbluAuth is not a constructor
```
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';`).

fix For ESM, use `import MeshbluAuth from 'express-meshblu-auth';`. For CommonJS, use `const MeshbluAuth = require('express-meshblu-auth');`.
```
Error: `uuid` must be a string
```
cause The `meshbluAuth.gatewayDevice()` method was called without providing a required `uuid` string argument, or the argument provided was not a string.

fix Ensure `meshbluAuth.gatewayDevice()` is called with a valid string representing the UUID, e.g., `app.use(meshbluAuth.gatewayDevice('your-device-uuid'));`

Warnings

breaking Starting with version 9.0.0, the `patchGlobal` option has been removed. Configurations that relied on `patchGlobal` must be updated.
Fix: Review your configuration for `patchGlobal` and refactor to remove its usage, as it's no longer supported.
gotcha 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`.
Fix: Ensure that `app.use(meshbluAuth.auth())` or `app.use(meshbluAuth.get())` appears before any `gateway()` or `gatewayDevice()` calls in your Express middleware setup.
breaking 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.
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.

Install

npm install express-meshblu-auth npm
yarn add express-meshblu-auth yarn
pnpm add express-meshblu-auth pnpm

Imports

MeshbluAuth
wrong:
```
import { MeshbluAuth } from 'express-meshblu-auth';
```
correct:
```
import MeshbluAuth from 'express-meshblu-auth';
```
The library primarily uses CommonJS default exports, which are imported as default in ESM.
MeshbluAuth (CommonJS)
```
const MeshbluAuth = require('express-meshblu-auth');
```
This is the documented and historically correct way to import the module in CommonJS environments.
meshbluAuth.auth()
wrong:
```
app.use(auth());
```
correct:
```
app.use(meshbluAuth.auth());
```
Authentication methods are instance methods of the `MeshbluAuth` class, not standalone functions.

Quickstart

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.

const express = require('express');
const MeshbluAuth = require('express-meshblu-auth');

const meshbluAuth = new MeshbluAuth({
  protocol: 'https',
  server: 'meshblu.octoblu.com',
  port: 443
});

const app = express();

// Retrieves the uuid & token from the request,
// validate them, then add them to request.meshbluAuth
app.use(meshbluAuth.auth());

// Retrieves the uuid & token from the request,
// validate them by retrieving the device, then:
// add credentials to request.meshbluAuth
// add device to request.meshbluDevice
app.use(meshbluAuth.get());

// Returns a 401 if no uuid & token were provided in the request
// Returns a 403 if the uuid & token provided were invalid
// calls next otherwise
// meshbluAuth.auth or meshbluAuth.get MUST BE CALLED FIRST in the middleware chain
app.use(meshbluAuth.gateway());

// Returns a 401 if no uuid & token were provided in the request
// Returns a 403 if the uuid & token provided were invalid
// Returns a 403 if the uuid given does not match the authorized uuid
// calls next otherwise
// meshbluAuth.auth or meshbluAuth.get MUST BE CALLED FIRST in the middleware chain
app.use(meshbluAuth.gatewayDevice('uuid'));

// Can be used instead of gateway. Redirects user if uuid & token were not
// provided or were not valid
app.use(meshbluAuth.gatewayRedirect('/login'));

app.use(function (request, response) {
  response.json({uuid: request.meshbluAuth.uuid, token: request.meshbluAuth.token});
});

app.listen(3333, () => {
  console.log('Meshblu auth example app listening on port 3333');
});

view raw JSON →