@inteli.city/node-red-contrib-websocket-plus 1.0.0

Node-RED WebSocket nodes with proxy support

npm install @inteli.city/node-red-contrib-websocket-plus

node-red-contrib-websocket-plus

Node-RED WebSocket nodes with JWT-enforced authentication, multitenant routing, and proxy support.

Drop-in replacement for the built-in Node-RED WebSocket nodes. Node types are prefixed websocket-plus to avoid conflicts with the official nodes. The nodes appear in the palette as ws.in+ and ws.out+.

Table of contents

• Core guarantees
• Nodes
  • websocket.in+
  • websocket.out+
  • websocket-plus-listener
    • Connection
    • Security — JWT validation
    • Tenant & scope
    • Advanced
  • websocket-plus-client
    • Connection
    • Authentication
    • Advanced
• msg._session
• Authentication flow
• Proxy support
• Installation
• License

Core guarantees

• Connections are rejected at the WebSocket handshake if the token is missing, invalid, or expired.
• Tenant identity is derived from a verified JWT claim and is immutable for the lifetime of the connection.
• Message routing enforces tenant boundaries — cross-tenant delivery requires explicit configuration.
• Flows receive pre-verified identity via msg._session; they do not need to re-authenticate.

Nodes

websocket.in+

Palette label: ws.in+ — type: websocket-plus in

Receives messages from a WebSocket connection and forwards them into the flow. Attach to a websocket-plus-listener (server) or websocket-plus-client (outbound) config node.

Every output message includes:

websocket.out+

Palette label: ws.out+ — type: websocket-plus out

Sends messages over a WebSocket connection. Routing is determined by the Message scope configured on the attached listener — not by message content.

Tenant identity cannot be overridden via message fields — routing always uses the verified msg._session.tenantId.

Reply pattern: receive on websocket.in+ → preserve msg._session → send on websocket.out+ with scope set to Session.

websocket-plus-listener (server config node)

Configures a server-side WebSocket endpoint. Authentication and tenant identity are enforced at the HTTP upgrade handshake — connections are rejected before any WebSocket frame is exchanged.

Connection

Security — JWT validation

The JWT is always read from the token query parameter. The parameter name is fixed and cannot be changed.

ws://host/path?token=<jwt>

Validation modes:

Token expiration (exp) is always checked when present, regardless of mode.

Tenant & scope

Advanced

websocket-plus-client (client config node)

Configures an outbound WebSocket connection.

Connection

Authentication

Auth mode None connects without credentials and will be rejected by any listener with JWT validation enabled.

Advanced

msg._session

Every message produced by a websocket.in+ node includes a _session object populated from the verified JWT claims:

{
  "type": "websocket",
  "id": "<connection-id>",
  "tenantId": "<verified-tenant-id>",
  "subject": "<jwt-sub-claim>",
  "authStatus": "verified",
  "routingScope": "tenant"
}

msg._session is the authoritative source of identity — flows should not recreate or modify it.

Authentication flow

Client → ws://host/path?token=<jwt>
            │
            ▼
  verifyClient (ws handshake)
    ├─ Extract token from query param "token" (fixed)
    ├─ Verify signature (HS256 / JWKS)
    ├─ Check exp, iss, aud
    ├─ Extract tenantId from claim
    └─ REJECT (401) on any failure
            │
            ▼ (accepted)
  handleConnection
    ├─ socket.nrAuth     = { claims, tenantId }
    ├─ socket.nrTenantId = tenantId
    └─ schedule terminate() at JWT exp (if authExpiry=disconnect)
            │
            ▼ (message received)
  msg._session = { id, tenantId, subject, authStatus, routingScope }
            │
            ▼ (websocket.out+)
  broadcast filtered by routingScope + tenantId

Proxy support

Outbound client connections respect standard proxy environment variables and Node-RED settings (checked in this order):

1. RED.settings.proxyOptions.https_proxy / http_proxy / no_proxy
2. https_proxy, HTTPS_PROXY, http_proxy, HTTP_PROXY, NO_PROXY environment variables

Installation

npm install @inteli.city/node-red-contrib-websocket-plus

License

Apache-2.0