node-red-contrib-tdn-eventsub 0.2.0 → 0.2.2

package/README.md

@@ -9,7 +9,7 @@ Node-RED nodes for an access-control **REST Server API**.
 | `get items` | Downloads all items (optionally filtered by type/division), stores to global context | request/reply |
 | `item status` | Subscribes to status of one or more item (source) ids and keeps waiting for updates indefinitely | continuous |
 
-All share one **REST server** config node: URL/host, port (default 8904), API key, optional auth scheme, optional server certificate fingerprint, optional client certificate.
+All share one **REST server** config node: URL/host, port (default 8904), API key (optional: can come from a credentials object instead), how to send it (Authorization or API key header), optional server certificate fingerprint, optional client certificate.
 
 Every node has a trigger input and **three outputs**:
 
@@ -34,13 +34,31 @@ Restart Node-RED. Nodes appear under **TDN REST**. Import the example via *Impor
 |---|---|
 | URL / host | `rest-server`, `192.168.1.10` or `https://rest-server`. `/api` path assumed. |
 | Port | Default `8904`. |
-| API key | Stored as a Node-RED credential; treated as opaque. |
-| Auth scheme | Blank (default): `Authorization: Basic base64(":" + key)`, accepted by server v9.0+. For older servers enter the API-key scheme token from your server's REST API docs; the key is then sent as `Authorization: <scheme> <key>`. |
+| API key | Optional. Stored as a Node-RED credential; treated as opaque. When set it is always used. When blank, each node reads a [credentials object](#credentials-object). |
+| Send key as | **Authorization header** (default) or **API key header**. |
+| Auth scheme | Authorization header only. Blank (default): `Authorization: Basic base64(":" + key)`, accepted by server v9.0+. For older servers enter the API-key scheme token from your server's REST API docs; the key is then sent as `Authorization: <scheme> <key>`. |
+| Header name | API key header only. Sent as `<header name>: <key>`; default `X-API-Key`. |
 | Cert fingerprint | Optional. SHA-256 (64 hex) or SHA-1 (40 hex) of the **server** certificate, colons optional. When set, the server's self-signed cert is accepted only if it matches; the check runs before any request is written, so the key is never sent to an impostor. A mismatch error prints the actual fingerprint. |
+| Plain HTTP (insecure) | Unencrypted `http://` whatever the URL says; certificate settings are ignored and the key travels in clear text. For bench testing against a non-TLS endpoint only. A TLS error like `unexpected message` or `wrong version number` usually means the endpoint needs this; the error text says so. |
 | Verify server certificate | Normal CA check when no fingerprint is set. |
 | Force links onto this host:port | The server builds `href`s from its own machine name. With this on, followed links keep path + query but use your configured host/port. With it off, a link that would downgrade `https` to `http` is refused. |
 | Client cert / key / PFX | Only if the REST Client item on the server has a thumbprint (pinned client certificate). |
 
+## Credentials object
+
+If the server config has **no API key stored** in Node-RED, every node takes the key from its **Credentials** property: a typedInput pointing at `msg`, `flow`, `global` or `env`, default `msg.credentials`. The value is either a bare key string or:
+
+```js
+{
+  apiKey: "XXXX-...",                          // required
+  authType: "authorization" | "header",        // default: server config
+  authScheme: "",                              // authorization only; blank = Basic
+  headerName: "X-API-Key"                      // header only
+}
+```
+
+Missing fields fall back to the server config. A stored key always takes precedence, and the credentials object is then ignored. A msg-borne credentials property is deleted from the msg before it is passed on, so the key doesn't reach debug nodes or downstream flows. The item status node reads the credentials once per trigger and keeps them for that subscription.
+
 Get the server fingerprint with:
 
 ```sh

package/examples/rest-basic.json

@@ -91,7 +91,9 @@
       [
         "dbg_err"
       ]
-    ]
+    ],
+    "creds": "credentials",
+    "credsType": "msg"
   },
   {
     "z": "rest_tab",
@@ -141,7 +143,9 @@
       [
         "dbg_err"
       ]
-    ]
+    ],
+    "creds": "credentials",
+    "credsType": "msg"
   },
   {
     "z": "rest_tab",
@@ -191,7 +195,9 @@
       [
         "dbg_err"
       ]
-    ]
+    ],
+    "creds": "credentials",
+    "credsType": "msg"
   },
   {
     "z": "rest_tab",
@@ -257,7 +263,9 @@
       [
         "dbg_err"
       ]
-    ]
+    ],
+    "creds": "credentials",
+    "credsType": "msg"
   },
   {
     "z": "rest_tab",
@@ -278,8 +286,11 @@
     "name": "REST Server",
     "url": "192.168.1.10",
     "port": 8904,
+    "authType": "authorization",
     "authScheme": "",
+    "headerName": "X-API-Key",
     "fingerprint": "",
+    "plainHttp": false,
     "rejectUnauthorized": true,
     "rewriteHrefs": true,
     "timeout": 30000,
@@ -287,4 +298,4 @@
     "keyPath": "",
     "pfxPath": ""
   }
-]
+]

package/lib/client.js

@@ -3,7 +3,9 @@
  * Minimal REST Server API client.
  *
  * - Auth: "Authorization: Basic base64(':' + key)" by default (server v9.0+),
- *   or "Authorization: <scheme> <key>" when a custom scheme token is configured
+ *   "Authorization: <scheme> <key>" when a custom scheme token is configured,
+ *   or the key in its own header ("X-API-Key: <key>" or a configured name)
+ * - Credentials can be fixed at construction or supplied later (withCredentials)
  * - HATEOAS: everything is discovered from GET /api (features.*.href)
  * - Optional server certificate pinning by SHA-1 or SHA-256 fingerprint
  *   (lets you talk to a self-signed REST Server without disabling verification)
@@ -36,6 +38,64 @@ class RestError extends Error {
     }
 }
 
+const AUTH_TYPES = ['authorization', 'header'];
+const DEFAULT_KEY_HEADER = 'X-API-Key';
+// headers we set ourselves; a key header must not replace them
+const RESERVED_HEADERS = ['host', 'accept', 'connection', 'content-type', 'content-length', 'transfer-encoding'];
+
+/**
+ * Normalise a credentials object. Accepts a bare key string, or
+ * { apiKey | key, authType, authScheme, headerName }; missing fields come from `defaults`.
+ */
+function normaliseCredentials(cred, defaults) {
+    const d = defaults || {};
+    const c = typeof cred === 'string' ? { apiKey: cred } : Object.assign({}, cred || {});
+    const pick = (v, dv) => (v === undefined || v === null || v === '' ? dv : v);
+    return {
+        apiKey: String(pick(c.apiKey !== undefined ? c.apiKey : c.key, d.apiKey) || '').trim(),
+        authType: String(pick(c.authType, d.authType) || 'authorization').trim().toLowerCase(),
+        authScheme: String(pick(c.authScheme, d.authScheme) || '').trim(),
+        headerName: String(pick(c.headerName, d.headerName) || DEFAULT_KEY_HEADER).trim()
+    };
+}
+
+/**
+ * Build the auth headers for one credential set:
+ *   authType 'authorization': Authorization: Basic base64(':' + key)  (blank scheme, server v9.0+)
+ *                             Authorization: <scheme> <key>           (custom scheme token)
+ *   authType 'header':        <headerName>: <key>                     (default X-API-Key)
+ */
+function buildAuthHeaders(cred) {
+    const c = normaliseCredentials(cred);
+    if (!c.apiKey) throw new RestError('No API key: store one in the server config or pass a credentials object', { code: 'ENOCREDS' });
+    if (/[\r\n]/.test(c.apiKey)) throw new RestError('API key must not contain line breaks');
+    if (!AUTH_TYPES.includes(c.authType)) throw new RestError(`Auth type must be one of: ${AUTH_TYPES.join(', ')}`);
+    if (c.authType === 'header') {
+        if (!TOKEN_RE.test(c.headerName) || RESERVED_HEADERS.includes(c.headerName.toLowerCase())) {
+            throw new RestError(`Invalid API key header name "${c.headerName}"`);
+        }
+        return { [c.headerName]: c.apiKey };
+    }
+    if (c.authScheme && !TOKEN_RE.test(c.authScheme)) throw new RestError('Auth scheme must be a single token (letters, digits, - _ . etc., no spaces)');
+    return {
+        Authorization: c.authScheme
+            ? c.authScheme + ' ' + c.apiKey
+            : 'Basic ' + Buffer.from(':' + c.apiKey, 'utf8').toString('base64')
+    };
+}
+
+// OpenSSL errors seen when the other end isn't speaking TLS at all
+const NOT_TLS_CODES = ['ERR_SSL_WRONG_VERSION_NUMBER', 'ERR_SSL_UNEXPECTED_MESSAGE', 'ERR_SSL_PACKET_LENGTH_TOO_LONG', 'ERR_SSL_HTTP_REQUEST', 'ERR_SSL_RECORD_LAYER_FAILURE'];
+
+/** Add a hint to TLS handshake errors that usually mean the endpoint is plain HTTP. */
+function notTlsHint(e) {
+    if (e && NOT_TLS_CODES.includes(e.code)) {
+        e.message = `TLS handshake failed (${e.code}): the endpoint may not be using TLS. ` +
+            'For a plain-HTTP endpoint tick "Plain HTTP (insecure)" in the server config. ' + e.message;
+    }
+    return e;
+}
+
 function abortError() {
     return new RestError('Request aborted', { code: 'ABORTED', aborted: true });
 }
@@ -45,12 +105,15 @@ class RestClient {
      * @param {object} o
      * @param {string} o.url            host, IP or URL (https:// assumed)
      * @param {number} [o.port]         default 8904
-     * @param {string} o.apiKey
-     * @param {string} [o.authScheme]   '' = Basic with ':<key>'; otherwise sent as '<scheme> <key>'
+     * @param {string} [o.apiKey]       optional; without it use withCredentials() per request source
+     * @param {string} [o.authType]     'authorization' (default) or 'header'
+     * @param {string} [o.authScheme]   authorization: '' = Basic with ':<key>'; otherwise '<scheme> <key>'
+     * @param {string} [o.headerName]   header: name of the key header (default X-API-Key)
      * @param {string} [o.fingerprint]  server cert SHA-1 (40 hex) or SHA-256 (64 hex), any separators
      * @param {boolean} [o.rejectUnauthorized] used only when no fingerprint is set
      * @param {string} [o.certPath] [o.keyPath] [o.pfxPath] [o.passphrase] client certificate
      * @param {boolean} [o.rewriteHrefs] force followed hrefs back onto the configured host:port
+     * @param {boolean} [o.plainHttp]    use unencrypted http:// whatever the URL says (bench/test only)
      * @param {number} [o.timeoutMs]    default request timeout
      */
     constructor(o) {
@@ -59,6 +122,7 @@ class RestClient {
         if (!raw) throw new RestError('No server URL configured');
         if (!/^https?:\/\//i.test(raw)) raw = 'https://' + raw;
         const u = new URL(raw);
+        if (o.plainHttp) u.protocol = 'http:';
         const port = parseInt(o.port, 10);
         if (port > 0) u.port = String(port);
         else if (!u.port) u.port = String(DEFAULT_PORT);
@@ -66,13 +130,12 @@ class RestClient {
         this.base = u;
         const path = u.pathname && u.pathname !== '/' ? u.pathname.replace(/\/+$/, '') : '/api';
         this.apiRoot = u.origin + path;
-        this.apiKey = String(o.apiKey || '').trim();
-        const scheme = String(o.authScheme || '').trim();
-        if (scheme && !TOKEN_RE.test(scheme)) throw new RestError('Auth scheme must be a single token (letters, digits, - _ . etc., no spaces)');
-        if (/[\r\n]/.test(this.apiKey)) throw new RestError('API key must not contain line breaks');
-        this.authHeader = scheme
-            ? scheme + ' ' + this.apiKey
-            : 'Basic ' + Buffer.from(':' + this.apiKey, 'utf8').toString('base64');
+        // no key here is fine: credentials can be supplied later with withCredentials().
+        // The auth settings are still checked now, so a bad scheme/header fails at deploy.
+        this.authDefaults = { authType: o.authType, authScheme: o.authScheme, headerName: o.headerName };
+        const hasKey = !!String(o.apiKey || '').trim();
+        const headers = buildAuthHeaders(Object.assign({}, o, { apiKey: hasKey ? o.apiKey : 'placeholder' }));
+        this.authHeaders = hasKey ? headers : null;
         this.fingerprint = normFp(o.fingerprint);
         if (this.fingerprint && this.fingerprint.length !== 40 && this.fingerprint.length !== 64) {
             throw new RestError('Certificate fingerprint must be SHA-1 (40 hex) or SHA-256 (64 hex)');
@@ -95,6 +158,20 @@ class RestClient {
         this._discoveryAt = 0;
     }
 
+    /**
+     * A client for the same server using other credentials (bare key string or
+     * { apiKey, authType, authScheme, headerName }; missing fields fall back to this
+     * client's auth settings). Shares TLS settings; has its own discovery cache,
+     * because what /api lists depends on the operator behind the key.
+     */
+    withCredentials(cred) {
+        const c = Object.create(this);
+        c.authHeaders = buildAuthHeaders(normaliseCredentials(cred, this.authDefaults));
+        c._discovery = null;
+        c._discoveryAt = 0;
+        return c;
+    }
+
     /** Resolve an href (absolute or relative) and optionally pin it to the configured host:port. */
     resolve(href) {
         const t = new URL(href, this.base.origin);
@@ -167,7 +244,7 @@ class RestClient {
             if (!net.isIP(host)) opts.servername = host;
 
             sock = tls.connect(opts);
-            sock.once('error', (e) => finish(e));
+            sock.once('error', (e) => finish(notTlsHint(e)));
             sock.once('secureConnect', () => {
                 if (pinning) {
                     const c = sock.getPeerCertificate();
@@ -195,13 +272,15 @@ class RestClient {
         const signal = opts.signal;
         // The socket is opened (and the server cert checked) before any header leaves,
         // so the API key is never sent to a server that fails the fingerprint pin.
+        if (!this.authHeaders) {
+            throw new RestError('No API key: store one in the server config or pass a credentials object', { code: 'ENOCREDS' });
+        }
         const sock = await this._connect(target, signal, timeoutMs);
         const payload = body === undefined || body === null ? null : Buffer.from(JSON.stringify(body));
-        const headers = {
-            Authorization: this.authHeader,
+        const headers = Object.assign({
             Accept: 'application/json',
             Connection: 'close'
-        };
+        }, this.authHeaders);
         if (payload) {
             headers['Content-Type'] = 'application/json';
             headers['Content-Length'] = payload.length;
@@ -319,4 +398,4 @@ class RestClient {
     }
 }
 
-module.exports = { RestClient, RestError, normFp, fmtFp, DEFAULT_PORT };
+module.exports = { RestClient, RestError, normaliseCredentials, buildAuthHeaders, normFp, fmtFp, DEFAULT_PORT, DEFAULT_KEY_HEADER };

package/lib/credentials.js

@@ -0,0 +1,42 @@
+'use strict';
+/**
+ * Credentials object lookup for functional nodes.
+ *
+ * Used only when the server config node has no API key stored in Node-RED's
+ * credentials. The node's "Credentials" property (typedInput: msg / flow / global / env)
+ * points at either a bare key string or
+ *   { apiKey, authType: 'authorization'|'header', authScheme, headerName }
+ */
+
+const CRED_TYPES = ['msg', 'flow', 'global', 'env'];
+
+/** Read node.creds/node.credsType config into the node (default msg.credentials). */
+function configureCreds(node, config) {
+    node.credsType = CRED_TYPES.includes(config.credsType) ? config.credsType : 'msg';
+    node.creds = config.creds === undefined || config.creds === null || config.creds === '' ? 'credentials' : String(config.creds).trim();
+}
+
+/** Resolve the credentials object for this message (undefined if absent). */
+function resolveCreds(RED, node, msg) {
+    if (node.server && node.server.hasStoredKey) return Promise.resolve(undefined); // stored key wins; don't touch context
+    return new Promise((resolve, reject) => {
+        RED.util.evaluateNodeProperty(node.creds, node.credsType, node, msg, (err, value) => {
+            if (err) reject(err); else resolve(value);
+        });
+    });
+}
+
+/** Remove a msg-borne credentials object so the key doesn't travel downstream. */
+function stripCreds(RED, node, msg) {
+    if (node.credsType !== 'msg' || !msg) return;
+    let parts;
+    try { parts = RED.util.normalisePropertyExpression(node.creds); } catch (e) { return; }
+    let obj = msg;
+    for (let i = 0; i < parts.length - 1; i++) {
+        obj = obj[parts[i]];
+        if (!obj || typeof obj !== 'object') return;
+    }
+    delete obj[parts[parts.length - 1]];
+}
+
+module.exports = { CRED_TYPES, configureCreds, resolveCreds, stripCreds };

package/nodes/rest-item-status.html

@@ -10,7 +10,9 @@
             maxRetryDelay: { value: 60000, validate: RED.validators.number() },
             emitTimeouts: { value: false },
             contextKey: { value: '' },
-            contextStore: { value: '' }
+            contextStore: { value: '' },
+            creds: { value: 'credentials' },
+            credsType: { value: 'msg' }
         },
         inputs: 1,
         outputs: 3,
@@ -19,6 +21,7 @@
         label: function () { return this.name || 'item status updates'; },
         paletteLabel: 'item status',
         oneditprepare: function () {
+            $('#node-input-creds').typedInput({ default: 'msg', types: ['msg', 'flow', 'global', 'env'], typeField: '#node-input-credsType' });
             var sel = $('#node-input-contextStore');
             var stores = (RED.settings.context && RED.settings.context.stores) || ['default'];
             sel.empty();
@@ -38,6 +41,11 @@
         <label for="node-input-server"><i class="fa fa-server"></i> Server</label>
         <input type="text" id="node-input-server">
     </div>
+    <div class="form-row">
+        <label for="node-input-creds"><i class="fa fa-key"></i> Credentials</label>
+        <input type="text" id="node-input-creds" style="width:70%">
+        <input type="hidden" id="node-input-credsType">
+    </div>
     <div class="form-row">
         <label for="node-input-pollDelay">Delay between waits (ms)</label>
         <input type="text" id="node-input-pollDelay" style="width:100px"> <span>0&ndash;20000</span>
@@ -79,7 +87,11 @@
         <dd>The source id(s): <code>"508"</code>, <code>"508,526"</code>, <code>["508","526"]</code>,
             <code>{"itemIds":["508","526"]}</code>, or an array of item objects with an <code>id</code> (e.g. straight from <i>get items</i> results).
             <code>msg.itemIds</code> takes precedence if present.</dd>
-        <dd>A new trigger replaces the running subscription. <code>payload</code> = <code>"stop"</code> or <code>msg.stop = true</code> stops it.</dd>
+        <dt class="optional">credentials <span class="property-type">string | object</span></dt><dd>Used only when the server config has no API key stored.
+            Read from the <i>Credentials</i> property (default <code>msg.credentials</code>; msg, flow, global or env): a bare key string, or
+            <code>{"apiKey":"...", "authType":"authorization"|"header", "authScheme":"...", "headerName":"X-API-Key"}</code>.
+            Missing fields fall back to the server config. A msg-borne credentials property is removed from the trigger msg.</dd>
+        <dd>Credentials are read once per trigger and kept for that subscription. A new trigger replaces the running subscription. <code>payload</code> = <code>"stop"</code> or <code>msg.stop = true</code> stops it.</dd>
     </dl>
     <h3>Outputs</h3>
     <ol class="node-ports">

package/nodes/rest-item-status.js

@@ -1,5 +1,6 @@
 'use strict';
 const { OUT_RESPONSE, send, setStatus, reportError, storeName, nowIso } = require('../lib/outputs');
+const { configureCreds, resolveCreds, stripCreds } = require('../lib/credentials');
 
 /**
  * Item status subscription (REST Server v8.30+, RESTStatus licence).
@@ -50,6 +51,7 @@ module.exports = function (RED) {
         node.emitTimeouts = config.emitTimeouts === true;
         node.contextKey = (config.contextKey || '').trim();
         node.contextStore = config.contextStore || '';
+        configureCreds(node, config);
 
         let run = null; // { ctrl, ids }
 
@@ -87,10 +89,11 @@ module.exports = function (RED) {
             });
         }
 
-        async function loop(ids, ctrl) {
+        async function loop(ids, ctrl, cred) {
             const signal = ctrl.signal;
             let client;
-            try { client = node.server.getClient(); } catch (e) { reportError(node, e); return; }
+            // credentials are taken once, from the trigger; the subscription keeps using them
+            try { client = node.server.getClient(cred); } catch (e) { reportError(node, e); return; }
 
             let next = null;
             let failures = 0;
@@ -161,13 +164,23 @@ module.exports = function (RED) {
         if (!node.server) setStatus(node, 'error', 'no server config');
         else node.status({ fill: 'grey', shape: 'ring', text: 'idle' });
 
-        node.on('input', function (msg, sendFn, done) {
+        node.on('input', async function (msg, sendFn, done) {
             done = done || function () {};
             if (isStop(msg)) {
+                stripCreds(RED, node, msg);
                 if (run) stop('stopped by input');
                 else setStatus(node, 'stopped', 'not running');
                 return done();
             }
+            let cred;
+            try {
+                cred = await resolveCreds(RED, node, msg);
+            } catch (e) {
+                reportError(node, e);
+                return done();
+            } finally {
+                stripCreds(RED, node, msg);
+            }
             if (!node.server) {
                 reportError(node, new Error('No REST server configured'));
                 return done();
@@ -180,7 +193,7 @@ module.exports = function (RED) {
             if (run) stop('replaced by new subscription');
             const ctrl = new AbortController();
             run = { ctrl, ids };
-            loop(ids, ctrl).catch((e) => reportError(node, e)).finally(() => {
+            loop(ids, ctrl, cred).catch((e) => reportError(node, e)).finally(() => {
                 if (run && run.ctrl === ctrl) run = null;
             });
             done(); // the trigger message is handled; the subscription carries on by itself

package/nodes/rest-lists.html

@@ -15,7 +15,9 @@
                 fields: { value: '' },
                 query: { value: '' },
                 maxPages: { value: 0, validate: RED.validators.number() },
-                includePages: { value: true }
+                includePages: { value: true },
+                creds: { value: 'credentials' },
+                credsType: { value: 'msg' }
             },
             inputs: 1,
             outputs: 3,
@@ -24,6 +26,7 @@
             label: function () { return this.name || ('get ' + d.palette); },
             paletteLabel: 'get ' + d.palette,
             oneditprepare: function () {
+                $('#node-input-creds').typedInput({ default: 'msg', types: ['msg', 'flow', 'global', 'env'], typeField: '#node-input-credsType' });
                 var sel = $('#node-input-contextStore');
                 var stores = (RED.settings.context && RED.settings.context.stores) || ['default'];
                 sel.empty();
@@ -45,6 +48,11 @@
         <label for="node-input-server"><i class="fa fa-server"></i> Server</label>
         <input type="text" id="node-input-server">
     </div>
+    <div class="form-row">
+        <label for="node-input-creds"><i class="fa fa-key"></i> Credentials</label>
+        <input type="text" id="node-input-creds" style="width:70%">
+        <input type="hidden" id="node-input-credsType">
+    </div>
     <div class="form-row">
         <label for="node-input-contextKey"><i class="fa fa-globe"></i> Global key</label>
         <input type="text" id="node-input-contextKey" placeholder="rest_accessGroups">
@@ -94,6 +102,10 @@
         <dt class="optional">fields <span class="property-type">string</span></dt><dd>Overrides the <i>Fields</i> setting.</dd>
         <dt class="optional">top / maxPages <span class="property-type">number</span></dt><dd>Override page size / page limit.</dd>
         <dt class="optional">contextKey <span class="property-type">string</span></dt><dd>Overrides the global key.</dd>
+        <dt class="optional">credentials <span class="property-type">string | object</span></dt><dd>Used only when the server config has no API key stored.
+            Read from the <i>Credentials</i> property (default <code>msg.credentials</code>; msg, flow, global or env): a bare key string, or
+            <code>{"apiKey":"...", "authType":"authorization"|"header", "authScheme":"...", "headerName":"X-API-Key"}</code>.
+            Missing fields fall back to the server config. A msg-borne credentials property is removed before the msg is passed on.</dd>
     </dl>
     <h3>Outputs</h3>
     <ol class="node-ports">
@@ -122,6 +134,11 @@
         <label for="node-input-server"><i class="fa fa-server"></i> Server</label>
         <input type="text" id="node-input-server">
     </div>
+    <div class="form-row">
+        <label for="node-input-creds"><i class="fa fa-key"></i> Credentials</label>
+        <input type="text" id="node-input-creds" style="width:70%">
+        <input type="hidden" id="node-input-credsType">
+    </div>
     <div class="form-row">
         <label for="node-input-contextKey"><i class="fa fa-globe"></i> Global key</label>
         <input type="text" id="node-input-contextKey" placeholder="rest_cardholders">
@@ -171,6 +188,10 @@
         <dt class="optional">fields <span class="property-type">string</span></dt><dd>Overrides the <i>Fields</i> setting.</dd>
         <dt class="optional">top / maxPages <span class="property-type">number</span></dt><dd>Override page size / page limit.</dd>
         <dt class="optional">contextKey <span class="property-type">string</span></dt><dd>Overrides the global key.</dd>
+        <dt class="optional">credentials <span class="property-type">string | object</span></dt><dd>Used only when the server config has no API key stored.
+            Read from the <i>Credentials</i> property (default <code>msg.credentials</code>; msg, flow, global or env): a bare key string, or
+            <code>{"apiKey":"...", "authType":"authorization"|"header", "authScheme":"...", "headerName":"X-API-Key"}</code>.
+            Missing fields fall back to the server config. A msg-borne credentials property is removed before the msg is passed on.</dd>
     </dl>
     <h3>Outputs</h3>
     <ol class="node-ports">
@@ -199,6 +220,11 @@
         <label for="node-input-server"><i class="fa fa-server"></i> Server</label>
         <input type="text" id="node-input-server">
     </div>
+    <div class="form-row">
+        <label for="node-input-creds"><i class="fa fa-key"></i> Credentials</label>
+        <input type="text" id="node-input-creds" style="width:70%">
+        <input type="hidden" id="node-input-credsType">
+    </div>
     <div class="form-row">
         <label for="node-input-contextKey"><i class="fa fa-globe"></i> Global key</label>
         <input type="text" id="node-input-contextKey" placeholder="rest_items">
@@ -248,6 +274,10 @@
         <dt class="optional">fields <span class="property-type">string</span></dt><dd>Overrides the <i>Fields</i> setting.</dd>
         <dt class="optional">top / maxPages <span class="property-type">number</span></dt><dd>Override page size / page limit.</dd>
         <dt class="optional">contextKey <span class="property-type">string</span></dt><dd>Overrides the global key.</dd>
+        <dt class="optional">credentials <span class="property-type">string | object</span></dt><dd>Used only when the server config has no API key stored.
+            Read from the <i>Credentials</i> property (default <code>msg.credentials</code>; msg, flow, global or env): a bare key string, or
+            <code>{"apiKey":"...", "authType":"authorization"|"header", "authScheme":"...", "headerName":"X-API-Key"}</code>.
+            Missing fields fall back to the server config. A msg-borne credentials property is removed before the msg is passed on.</dd>
     </dl>
     <h3>Outputs</h3>
     <ol class="node-ports">

package/nodes/rest-lists.js

@@ -1,6 +1,7 @@
 'use strict';
 const { RestClient } = require('../lib/client');
 const { OUT_RESPONSE, send, setStatus, reportError, storeName, nowIso } = require('../lib/outputs');
+const { configureCreds, resolveCreds, stripCreds } = require('../lib/credentials');
 
 /**
  * Request/reply "list" nodes. Each trigger:
@@ -28,6 +29,7 @@ module.exports = function (RED) {
             node.query = (config.query || '').trim();
             node.maxPages = parseInt(config.maxPages, 10) || 0;
             node.includePages = config.includePages !== false;
+            configureCreds(node, config);
 
             let running = null; // AbortController of in-flight run
 
@@ -48,7 +50,13 @@ module.exports = function (RED) {
                 running = ctrl;
                 const started = Date.now();
                 try {
-                    const client = node.server.getClient();
+                    let cred;
+                    try {
+                        cred = await resolveCreds(RED, node, msg);
+                    } finally {
+                        stripCreds(RED, node, msg); // never pass a key downstream, even on error
+                    }
+                    const client = node.server.getClient(cred);
                     setStatus(node, 'requesting', `requesting ${def.label}`);
                     const firstHref = await client.feature(def.feature, { signal: ctrl.signal });
 

package/nodes/rest-server.html

@@ -5,7 +5,9 @@
             name: { value: '' },
             url: { value: '', required: true },
             port: { value: 8904, required: true, validate: RED.validators.number() },
+            authType: { value: 'authorization' },
             authScheme: { value: '', validate: function (v) { return !v || /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(String(v).trim()); } },
+            headerName: { value: 'X-API-Key', validate: function (v) { return !v || /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(String(v).trim()); } },
             fingerprint: {
                 value: '',
                 validate: function (v) {
@@ -14,6 +16,7 @@
                     return h.length === 40 || h.length === 64;
                 }
             },
+            plainHttp: { value: false },
             rejectUnauthorized: { value: true },
             rewriteHrefs: { value: true },
             timeout: { value: 30000, validate: RED.validators.number() },
@@ -22,11 +25,28 @@
             pfxPath: { value: '' }
         },
         credentials: {
-            apiKey: { type: 'password', required: true },
+            apiKey: { type: 'password' },
             passphrase: { type: 'password' }
         },
         label: function () {
             return this.name || ((this.url || 'rest-server') + ':' + (this.port || 8904));
+        },
+        oneditprepare: function () {
+            var sync = function () {
+                var header = $('#node-config-input-authType').val() === 'header';
+                $('.tdn-rest-auth-scheme').toggle(!header);
+                $('.tdn-rest-auth-header').toggle(header);
+            };
+            if (!this.authType) $('#node-config-input-authType').val('authorization');
+            $('#node-config-input-authType').on('change', sync);
+            sync();
+            var syncTls = function () {
+                var plain = $('#node-config-input-plainHttp').is(':checked');
+                $('.tdn-rest-tls').toggle(!plain);
+                $('.tdn-rest-plain-warning').toggle(plain);
+            };
+            $('#node-config-input-plainHttp').on('change', syncTls);
+            syncTls();
         }
     });
 </script>
@@ -46,17 +66,34 @@
     </div>
     <div class="form-row">
         <label for="node-config-input-apiKey"><i class="fa fa-key"></i> API key</label>
-        <input type="password" id="node-config-input-apiKey" placeholder="XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX">
+        <input type="password" id="node-config-input-apiKey" placeholder="blank = supplied per node (credentials object)">
     </div>
     <div class="form-row">
-        <label for="node-config-input-authScheme"><i class="fa fa-lock"></i> Auth scheme</label>
+        <label for="node-config-input-authType"><i class="fa fa-lock"></i> Send key as</label>
+        <select id="node-config-input-authType" style="width:70%">
+            <option value="authorization">Authorization header</option>
+            <option value="header">API key header</option>
+        </select>
+    </div>
+    <div class="form-row tdn-rest-auth-scheme">
+        <label for="node-config-input-authScheme">Auth scheme</label>
         <input type="text" id="node-config-input-authScheme" placeholder="blank = Basic (server v9.0+)">
     </div>
+    <div class="form-row tdn-rest-auth-header">
+        <label for="node-config-input-headerName">Header name</label>
+        <input type="text" id="node-config-input-headerName" placeholder="X-API-Key">
+    </div>
     <div class="form-row">
+        <label>&nbsp;</label>
+        <input type="checkbox" id="node-config-input-plainHttp" style="display:inline-block;width:auto;vertical-align:top">
+        <label for="node-config-input-plainHttp" style="width:auto">Plain HTTP (insecure, no TLS)</label>
+    </div>
+    <div class="form-tips tdn-rest-plain-warning"><b>Insecure:</b> the API key and all data are sent unencrypted. Use only for bench testing against a non-TLS endpoint.</div>
+    <div class="form-row tdn-rest-tls">
         <label for="node-config-input-fingerprint"><i class="fa fa-certificate"></i> Cert fingerprint</label>
         <input type="text" id="node-config-input-fingerprint" placeholder="optional SHA-256 or SHA-1 of server cert">
     </div>
-    <div class="form-row">
+    <div class="form-row tdn-rest-tls">
         <label>&nbsp;</label>
         <input type="checkbox" id="node-config-input-rejectUnauthorized" style="display:inline-block;width:auto;vertical-align:top">
         <label for="node-config-input-rejectUnauthorized" style="width:auto">Verify server certificate against CA (ignored when a fingerprint is set)</label>
@@ -70,6 +107,7 @@
         <label for="node-config-input-timeout"><i class="fa fa-clock-o"></i> Timeout (ms)</label>
         <input type="text" id="node-config-input-timeout" placeholder="30000" style="width:100px">
     </div>
+    <div class="tdn-rest-tls">
     <hr>
     <div class="form-tips">Client certificate &mdash; only if the REST Client item on the server has a thumbprint set. Use PEM cert + key, <i>or</i> a PFX.</div>
     <div class="form-row">
@@ -88,6 +126,7 @@
         <label for="node-config-input-passphrase">Passphrase</label>
         <input type="password" id="node-config-input-passphrase">
     </div>
+    </div>
 </script>
 
 <script type="text/html" data-help-name="tdn-rest-server">
@@ -99,16 +138,26 @@
         <dt>Port <span class="property-type">number</span></dt>
         <dd>REST port, default <code>8904</code>.</dd>
         <dt>API key <span class="property-type">credential</span></dt>
-        <dd>Stored as a Node-RED credential and treated as opaque.</dd>
+        <dd>Optional. Stored as a Node-RED credential and treated as opaque. When set, it is always used.
+            When blank, each node takes the key from its <i>Credentials</i> object (default <code>msg.credentials</code>);
+            see the node's help.</dd>
+        <dt>Send key as</dt>
+        <dd><b>Authorization header</b> (default) or <b>API key header</b>. A credentials object can override this per message.</dd>
         <dt class="optional">Auth scheme <span class="property-type">string</span></dt>
-        <dd>Blank (default): the key is sent as <code>Authorization: Basic base64(":" + key)</code>, accepted by server v9.0+.
+        <dd>Authorization header only. Blank (default): <code>Authorization: Basic base64(":" + key)</code>, accepted by server v9.0+.
             For older servers, enter the API-key scheme token from your server's REST API documentation;
             the key is then sent as <code>Authorization: &lt;scheme&gt; &lt;key&gt;</code>.</dd>
+        <dt class="optional">Header name <span class="property-type">string</span></dt>
+        <dd>API key header only. The key is sent as <code>&lt;header name&gt;: &lt;key&gt;</code>; default <code>X-API-Key</code>.</dd>
         <dt class="optional">Cert fingerprint <span class="property-type">string</span></dt>
         <dd>SHA-256 (64 hex) or SHA-1 (40 hex) of the <b>server</b> certificate, colons optional.
             When set, the connection is accepted only if the presented certificate matches, even if it is self-signed.
             The check happens before any request (and therefore the API key) is sent.
             A mismatch error reports the actual fingerprint so you can copy it.</dd>
+        <dt>Plain HTTP (insecure)</dt>
+        <dd>Connect with unencrypted <code>http://</code> whatever the URL says. The API key travels in clear text and the
+            certificate settings are ignored, so use it only for bench testing against a non-TLS endpoint. A TLS handshake error such as
+            <code>unexpected message</code> or <code>wrong version number</code> usually means the endpoint needs this.</dd>
         <dt>Verify server certificate</dt>
         <dd>Normal CA verification when no fingerprint is set. Untick only for lab use.</dd>
         <dt>Force returned links back onto this host:port</dt>

package/nodes/rest-server.js

@@ -1,5 +1,8 @@
 'use strict';
-const { RestClient } = require('../lib/client');
+const crypto = require('crypto');
+const { RestClient, RestError, normaliseCredentials } = require('../lib/client');
+
+const MAX_CRED_CLIENTS = 20; // per-credential clients kept (each holds its own discovery cache)
 
 module.exports = function (RED) {
     function RestServerNode(config) {
@@ -8,15 +11,19 @@ module.exports = function (RED) {
         this.url = config.url;
         this.port = config.port;
         this.fingerprint = config.fingerprint;
+        this.authType = config.authType || 'authorization';
         this.authScheme = (config.authScheme || '').trim();
+        this.headerName = (config.headerName || '').trim();
         this.rejectUnauthorized = config.rejectUnauthorized !== false;
         this.rewriteHrefs = config.rewriteHrefs !== false;
+        this.plainHttp = config.plainHttp === true;
         this.timeout = parseInt(config.timeout, 10) || 30000;
         this.certPath = config.certPath;
         this.keyPath = config.keyPath;
         this.pfxPath = config.pfxPath;
 
         const creds = this.credentials || {};
+        this.hasStoredKey = !!String(creds.apiKey || '').trim();
         this.client = null;
         this.clientError = null;
         try {
@@ -24,28 +31,54 @@ module.exports = function (RED) {
                 url: this.url,
                 port: this.port,
                 apiKey: creds.apiKey,
+                authType: this.authType,
                 authScheme: this.authScheme,
+                headerName: this.headerName,
                 fingerprint: this.fingerprint,
                 rejectUnauthorized: this.rejectUnauthorized,
                 rewriteHrefs: this.rewriteHrefs,
+                plainHttp: this.plainHttp,
                 timeoutMs: this.timeout,
                 certPath: this.certPath,
                 keyPath: this.keyPath,
                 pfxPath: this.pfxPath,
                 passphrase: creds.passphrase
             });
-            if (!creds.apiKey) this.clientError = new Error('No API key configured');
-            if (this.client.base.protocol === 'http:') this.warn('REST server URL is http:// - the API key will be sent unencrypted');
+            if (this.client.base.protocol === 'http:') {
+                this.warn('REST server uses plain HTTP - the API key will be sent unencrypted' +
+                    (this.fingerprint || this.certPath || this.pfxPath ? '; certificate settings are ignored' : ''));
+            }
         } catch (e) {
             this.clientError = e;
             this.error('REST server config: ' + e.message);
         }
 
-        /** Returns the client or throws the configuration error. */
-        this.getClient = () => {
+        const credClients = new Map(); // sha256(normalised cred) -> client
+
+        /**
+         * Returns a client or throws.
+         * - API key stored in the Node-RED credentials: always used; `cred` is ignored.
+         * - Otherwise `cred` (bare key string or { apiKey, authType, authScheme, headerName })
+         *   supplies the key; missing auth fields come from this config node.
+         */
+        this.getClient = (cred) => {
             if (this.clientError) throw this.clientError;
-            return this.client;
+            if (this.hasStoredKey) return this.client;
+            if (cred === undefined || cred === null || cred === '') {
+                throw new RestError('No API key: none stored in the server config and no credentials object supplied', { code: 'ENOCREDS' });
+            }
+            const norm = normaliseCredentials(cred, this.client.authDefaults);
+            const id = crypto.createHash('sha256').update(JSON.stringify(norm)).digest('hex');
+            let c = credClients.get(id);
+            if (!c) {
+                c = this.client.withCredentials(norm);
+                if (credClients.size >= MAX_CRED_CLIENTS) credClients.delete(credClients.keys().next().value);
+                credClients.set(id, c);
+            }
+            return c;
         };
+
+        this.on('close', () => credClients.clear());
     }
 
     RED.nodes.registerType('tdn-rest-server', RestServerNode, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-tdn-eventsub",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Node-RED nodes for an access-control REST Server API: access groups, cardholders and items lists to global context, plus continuous item status subscriptions.",
   "main": "lib/client.js",
   "scripts": {