node-red-contrib-tdn-eventsub 0.1.0 → 0.2.1

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,30 @@ 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. |
 | 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,7 +286,9 @@
     "name": "REST Server",
     "url": "192.168.1.10",
     "port": 8904,
+    "authType": "authorization",
     "authScheme": "",
+    "headerName": "X-API-Key",
     "fingerprint": "",
     "rejectUnauthorized": true,
     "rewriteHrefs": true,
@@ -287,4 +297,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,52 @@ 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')
+    };
+}
+
 function abortError() {
     return new RestError('Request aborted', { code: 'ABORTED', aborted: true });
 }
@@ -45,8 +93,10 @@ 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
@@ -66,13 +116,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 +144,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);
@@ -195,13 +258,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 +384,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) {
@@ -22,11 +24,21 @@
             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();
         }
     });
 </script>
@@ -46,12 +58,23 @@
     </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 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">
@@ -99,11 +122,17 @@
         <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.

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,7 +11,9 @@ 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.timeout = parseInt(config.timeout, 10) || 30000;
@@ -17,6 +22,7 @@ module.exports = function (RED) {
         this.pfxPath = config.pfxPath;
 
         const creds = this.credentials || {};
+        this.hasStoredKey = !!String(creds.apiKey || '').trim();
         this.client = null;
         this.clientError = null;
         try {
@@ -24,7 +30,9 @@ 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,
@@ -34,18 +42,38 @@ module.exports = function (RED) {
                 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');
         } 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.1.0",
+  "version": "0.2.1",
   "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": {