geonix 1.23.6 → 1.30.2

package/src/Connection.js

@@ -4,6 +4,7 @@ import { Stream } from "./Stream.js";
 import { webserver } from "./WebServer.js";
 import { logger } from "./Logger.js";
 import { decode, encode } from "./Codec.js";
+import { encryptPayload, decryptPayload, encryptSubject, wrapSubscription } from "./Crypto.js";
 
 // -------------------------------------------------------------------------------------------------
 const CONNECTION_TIMEOUT = 10000;
@@ -12,23 +13,23 @@ const defaultRequestOptions = {
     timeout: 300000
 };
 
+const DEFAULT_CONNECTION_COUNT = 1;
+
 const defaultConnectionOptions = {
     timeout: CONNECTION_TIMEOUT,
     reconnect: true,
-    debug: process.env.TRANSPORT_DEBUG === "true",
+    debug: (process.env.GX_TRANSPORT_DEBUG || process.env.TRANSPORT_DEBUG) === "true",
     maxReconnectAttempts: 30,
     pingInterval: 30000,
-    waitOnFirstConnect: true,
-    connections: 1
+    waitOnFirstConnect: true
 };
 // -------------------------------------------------------------------------------------------------
 
 /**
- * Connection class is responsible for starting a connection to a NATS server and provides shortcut
- * methods for publish, subscribe and request methods of the NATS client.
- * 
- * It is implemented as an singleton so that multiple services can be implemented in the same
- * process while using just a single connection to the NATS server.
+ * Manages one or more NATS connections and exposes publish, subscribe, and request helpers.
+ * Instantiated as a singleton (`connection`) so multiple services in the same process share a
+ * single pool of connections. Optional subject-level HMAC encryption and payload AES-GCM
+ * encryption are activated by setting the `GX_SECRET` environment variable.
  */
 class Connection {
 
@@ -39,22 +40,26 @@ class Connection {
     #connectionRoundRobin = 0;
 
     #getConnection() {
-        this.#connectionRoundRobin = ++this.#connectionRoundRobin % this.#connections.length;
-        return this.#connections[this.#connectionRoundRobin];
+        return this.#connections[this.#connectionRoundRobin++ % this.#connections.length];
     }
 
     /**
-     * Initiates connection to transport
-     * @param {string} transport 
+     * Connects to the NATS transport. Called automatically on module load via the singleton.
+     *
+     * @param {string} [transport] - NATS URL, optionally including credentials and query-string
+     *   options (e.g. `nats://user:pass@host:4222?connections=2`). Defaults to `GX_TRANSPORT`,
+     *   `TRANSPORT`, or `nats://localhost`.
+     * @returns {Promise<void>}
      */
-    async start(transport = process.env.TRANSPORT || "nats://localhost") {
-        const options = {
+    async start(transport = process.env.GX_TRANSPORT || process.env.TRANSPORT || "nats://localhost") {
+        const { connections: _connectionCount, ...natsOptions } = {
             ...defaultConnectionOptions,
             ...parseURL(transport)
         };
+        const connectionCount = parseInt(_connectionCount) || DEFAULT_CONNECTION_COUNT;
 
-        for (let i = 0; i < options.connections; i++) {
-            this.#connections.push(await connect(options));
+        for (let i = 0; i < connectionCount; i++) {
+            this.#connections.push(await connect(natsOptions));
         }
 
         logger.info("gx.connection.connected");
@@ -62,17 +67,28 @@ class Connection {
         this.#ready = true;
 
         this.monitorStatus();
-        this.waitUntilClosed();
+        this.waitUntilClosed().catch(e => logger.error("gx.connection.waitUntilClosed:", e));
     }
 
-    async monitorStatus() {
-        for await (const event of this.#getConnection().status()) {
-            logger.info("gx.connection.status", JSON.stringify(event));
+    /**
+     * Starts background logging of NATS status events for all connections.
+     * @returns {void}
+     */
+    monitorStatus() {
+        for (const conn of this.#connections) {
+            (async () => {
+                for await (const event of conn.status()) {
+                    logger.debug("gx.connection.status", JSON.stringify(event));
+                }
+            })().catch(e => logger.error("gx.connection.status:", e));
         }
     }
 
     /**
-     * Wait for the connection to be safely closed
+     * Resolves once all NATS connections have been fully closed, then stops the web server and
+     * exits the process (exit code 0 on graceful drain, 1 on unexpected closure).
+     *
+     * @returns {Promise<void>}
      */
     async waitUntilClosed() {
         // wait for all connections to be closed
@@ -86,11 +102,13 @@ class Connection {
         await sleep(5000);
 
         logger.info("gx.terminate");
-        process.exit(1);
+        process.exit(this.#draining ? 0 : 1);
     }
 
     /**
-     * Wait for the connection to be fully established
+     * Resolves once the NATS connection pool is ready to publish and subscribe.
+     *
+     * @returns {Promise<void>}
      */
     async waitUntilReady() {
         while (!this.#ready) {
@@ -114,17 +132,17 @@ class Connection {
 
         // if payload is too big, convert it to Stream
         if (payload.length > this.getMaxPayloadSize()) {
-            payload = encode(Stream(JSON.stringify(json)));
+            payload = encode(Stream(Buffer.from(payload)));
         }
 
-        await this.#getConnection().publish(subject, payload);
+        await this.#getConnection().publish(encryptSubject(subject), encryptPayload(payload));
     }
 
     /**
      * Publish RAW
-     * 
-     * @param {string} subject 
-     * @param {string | Buffer} data 
+     *
+     * @param {string} subject
+     * @param {string | Buffer} data
      * @returns void
      */
     async publishRaw(subject, data) {
@@ -132,7 +150,7 @@ class Connection {
             return;
         }
 
-        await this.#getConnection().publish(subject, data);
+        await this.#getConnection().publish(encryptSubject(subject), encryptPayload(data != null ? Buffer.from(data) : Buffer.alloc(0)));
     }
 
     /**
@@ -159,24 +177,40 @@ class Connection {
         }
 
         const nc = this.#getConnection();
-        let response = await nc.subscribe(respondTo, { max: 1, ...options });
+        const response = await nc.subscribe(encryptSubject(respondTo), { max: 1, ...options });
 
-        await nc.publish(subject, payload);
+        await nc.publish(encryptSubject(subject), encryptPayload(payload));
 
         const event = await getFirstItemFromAsyncIterable(response);
-        return decode(event.data);
+        return decode(decryptPayload(event.data));
     }
 
+    /**
+     * Subscribes to a NATS subject and returns an async-iterable subscription. If payload
+     * encryption is enabled each message is transparently decrypted before being yielded.
+     *
+     * @param {string} subject - NATS subject to subscribe to.
+     * @param {object} [options] - NATS subscription options (e.g. `queue`, `max`).
+     * @returns {Promise<AsyncIterable>} Subscription iterable.
+     */
     async subscribe(subject, options) {
-        return this.#getConnection().subscribe(subject, options);
+        return wrapSubscription(await this.#getConnection().subscribe(encryptSubject(subject), options));
     }
 
-    async unsubscribe(subscription) {
+    /**
+     * Cancels an active subscription.
+     *
+     * @param {AsyncIterable} subscription - Subscription returned by {@link subscribe}.
+     * @returns {void}
+     */
+    unsubscribe(subscription) {
         subscription.unsubscribe();
     }
 
     /**
-     * 
+     * Returns the maximum NATS message payload size in bytes as reported by the server.
+     * Falls back to 512 KB if the connection info is not yet available.
+     *
      * @returns {number}
      */
     getMaxPayloadSize() {
@@ -184,10 +218,20 @@ class Connection {
         return nc?.info?.max_payload || 1024 * 512;
     }
 
+    /**
+     * Returns `true` after all NATS connections have been fully closed.
+     *
+     * @returns {boolean}
+     */
     isClosed() {
         return this.#closed;
     }
 
+    /**
+     * Drains all active NATS connections, flushing pending messages before closing them.
+     *
+     * @returns {Promise<void>}
+     */
     async drain() {
         this.#draining = true;
 
@@ -196,13 +240,23 @@ class Connection {
 
 }
 
+/**
+ * Singleton {@link Connection} instance shared across the process. Started automatically on
+ * module load; callers should use `connection.waitUntilReady()` before publishing or subscribing.
+ *
+ * @type {Connection}
+ */
 export const connection = new Connection();
-connection.start();
+connection.start().catch(e => {
+    logger.error("gx.connection.start:", e);
+    process.exit(1);
+});
 
+/**
+ * Initiates a graceful shutdown by draining all NATS connections.
+ *
+ * @returns {void}
+ */
 export const stopConnection = () => {
-    if (!connection) {
-        return;
-    }
-
     connection.drain();
 };

package/src/Crypto.js

@@ -0,0 +1,103 @@
+import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes } from "crypto";
+
+const _secret = process.env.GX_SECRET || null;
+
+// Subject key is derived separately so HMAC-subject and AES-payload never share key material.
+const _subjectKey = _secret ? createHash("sha256").update(_secret + "\x00subject").digest() : null;
+
+/**
+ * AES-256-GCM key derived from `GX_SECRET`, or `null` when encryption is disabled.
+ * Used internally by {@link encryptPayload} and {@link decryptPayload}.
+ *
+ * @type {Buffer|null}
+ */
+export const _payloadKey = _secret ? createHash("sha256").update(_secret + "\x00payload").digest() : null;
+
+/**
+ * Encrypts `data` with AES-256-GCM using {@link _payloadKey}. Returns `data` unchanged when
+ * encryption is disabled. The output format is `[12-byte IV][16-byte auth tag][ciphertext]`.
+ *
+ * @param {Buffer|null} data - Plaintext bytes to encrypt.
+ * @returns {Buffer}
+ */
+export function encryptPayload(data) {
+    if (!_payloadKey) { return data; }
+    const buf = data != null ? Buffer.from(data) : Buffer.alloc(0);
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", _payloadKey, iv);
+    const encrypted = cipher.update(buf);
+    cipher.final();
+    const out = Buffer.allocUnsafe(12 + 16 + encrypted.length);
+    iv.copy(out, 0);
+    cipher.getAuthTag().copy(out, 12);
+    encrypted.copy(out, 28);
+    return out;
+}
+
+/**
+ * Decrypts a buffer produced by {@link encryptPayload}. Returns `data` unchanged when
+ * encryption is disabled. Expects the layout `[12-byte IV][16-byte auth tag][ciphertext]`.
+ *
+ * @param {Buffer} data - Encrypted bytes to decrypt.
+ * @returns {Buffer}
+ */
+export function decryptPayload(data) {
+    if (!_payloadKey) { return data; }
+    const buf = Buffer.from(data);
+    const decipher = createDecipheriv("aes-256-gcm", _payloadKey, buf.subarray(0, 12));
+    decipher.setAuthTag(buf.subarray(12, 28));
+    const decrypted = decipher.update(buf.subarray(28));
+    decipher.final();
+    return decrypted;
+}
+
+/**
+ * Encrypts each dot-separated segment of a NATS subject using HMAC-SHA256, truncated to 32 hex
+ * characters. Wildcard tokens (`*`, `>`) are passed through unchanged so NATS subscription
+ * semantics are preserved. Returns the subject unchanged when encryption is disabled.
+ *
+ * @param {string} subject - Plain NATS subject string (e.g. `"gx2.service.abc"`).
+ * @returns {string} Encrypted subject string.
+ */
+export function encryptSubject(subject) {
+    if (!_subjectKey) {
+        return subject;
+    }
+
+    return subject.split(".").map(seg =>
+        (seg === "*" || seg === ">") ? seg
+            : createHmac("sha256", _subjectKey).update(seg).digest("hex").slice(0, 32)
+    ).join(".");
+}
+
+/**
+ * Wraps a NATS subscription so that every incoming message's `data` field is transparently
+ * decrypted before being yielded. Returns the subscription unchanged when encryption is
+ * disabled.
+ *
+ * @param {object} sub - NATS subscription object with `[Symbol.asyncIterator]`, `drain`, and `unsubscribe`.
+ * @returns {object} Wrapped subscription with the same interface.
+ */
+export function wrapSubscription(sub) {
+    if (!_payloadKey) {
+        return sub;
+    }
+
+    return {
+        [Symbol.asyncIterator]() {
+            const iter = sub[Symbol.asyncIterator]();
+            return {
+                async next() {
+                    const { value, done } = await iter.next();
+                    if (done) {
+                        return { value, done };
+                    }
+
+                    return { value: { ...value, data: decryptPayload(value.data) }, done: false };
+                }
+            };
+        },
+        drain: () => sub.drain(),
+        unsubscribe: () => sub.unsubscribe(),
+    };
+}