@openziti/ziti-sdk-nodejs 0.28.1 → 0.29.0

package/configure

@@ -12,3 +12,4 @@ else
 fi
 
 ${basedir}/node_modules/.bin/cmake-js configure ${arch_arg} -- --preset=${preset}
+# ${basedir}/node_modules/.bin/cmake-js configure ${arch_arg} -- --preset=${preset} -DZITI_SDK_DIR=/Users/curt/Repos/nf/github/ziti-sdk-c

package/lib/extAuthToken.js

@@ -0,0 +1,36 @@
+/*
+Copyright NetFoundry Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/**
+ * Provide an external JWT token to authenticate with the Ziti Controller.
+ *
+ * This function is used when the Ziti identity requires external authentication
+ * (e.g., OIDC). The auth event callback provided to init() will be called with
+ * the authentication details, and this function should be called with the JWT
+ * obtained from the external identity provider.
+ *
+ * @param {string} jwtToken - The JWT token obtained from the external identity provider
+ * @returns {number} 0 on success, -22 (ZITI_INVALID_STATE) if context not initialized
+ * @throws {Error} If jwtToken is not a non-empty string
+ */
+const extAuthToken = (jwtToken) => {
+    if (typeof jwtToken !== 'string' || jwtToken.length === 0) {
+        throw new Error('JWT token must be a non-empty string');
+    }
+    return ziti.ziti_ext_auth_token(jwtToken);
+};
+
+exports.extAuthToken = extAuthToken;

package/lib/httpRequest.js

@@ -61,7 +61,7 @@ const httpRequest = ( serviceName, schemeHostPort, method, path, headers, on_req
     if (typeof on_resp_cb === 'undefined') {
         _on_resp_cb = on_resp;
     } else {
-        _on_resp_cb = on_req_cb;
+        _on_resp_cb = on_resp_cb;
     }
 
     if (typeof on_resp_data_cb === 'undefined') {
@@ -70,8 +70,14 @@ const httpRequest = ( serviceName, schemeHostPort, method, path, headers, on_req
         _on_resp_data_cb = on_resp_data_cb;
     }
 
-    ziti.Ziti_http_request( serviceName, schemeHostPort, method, path, headers, _on_req_cb, _on_resp_cb, _on_resp_data_cb );
-
+    return new Promise((resolve, reject) => {
+        try {
+            let req = ziti.Ziti_http_request( serviceName, schemeHostPort, method, path, headers, _on_req_cb, _on_resp_cb, _on_resp_data_cb );
+            return resolve( req );
+        } catch (e) {
+          reject(e);
+        }
+    });
 };
 
 

package/lib/init.js

@@ -15,19 +15,27 @@ limitations under the License.
 */
 
 
- const init = ( identityPath ) => {
+/**
+ * Initialize the Ziti session and authenticate with control plane.
+ *
+ * @param {string} identityPath - File system path to the identity file.
+ * @param {function} [onAuthEvent] - Optional callback for authentication events.
+ *   Called with an object containing { action, type, detail } when auth events occur.
+ *   - action: 'login_external', 'select_external', 'cannot_continue', 'prompt_totp', 'prompt_pin'
+ *   - type: The authentication type (e.g., 'oidc')
+ *   - detail: Additional details (e.g., the OIDC provider URL)
+ * @returns {Promise<void>} Resolves when initialization is complete.
+ */
+const init = ( identityPath, onAuthEvent ) => {
 
   return new Promise((resolve, reject) => {
-
       try {
           ziti.ziti_init( identityPath, ( result ) => {
-
               if (result instanceof Error) {
                   return reject(result);
               }
-
               return resolve( result );
-          });
+          }, onAuthEvent);
       } catch (e) {
           reject(e);
       }

package/lib/initExternalAuth.js

@@ -0,0 +1,70 @@
+/*
+Copyright NetFoundry Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+
+/**
+ * Initialize external authentication with a Ziti controller.
+ *
+ * @param {string} controllerHost - The hostname of the Ziti controller (e.g., "ctrl.example.com:1280")
+ * @param {string} token - The external authentication token
+ * @returns {number} 0 on success, error code on failure
+ */
+const initExternalAuth = ( controllerHost, token ) => {
+
+    if (typeof controllerHost !== 'string' || controllerHost.length === 0) {
+        throw new Error('controllerHost must be a non-empty string');
+    }
+    if (typeof token !== 'string' || token.length === 0) {
+        throw new Error('token must be a non-empty string');
+    }
+
+    return new Promise((resolve, reject) => {   
+
+      try {
+        ziti.ziti_init_external_auth( controllerHost, async ( cfg ) => {
+
+            if (cfg instanceof Error) {
+                return reject(cfg);
+            }
+
+            function onAuthEvent(event) {
+    
+                if (event.action === 'login_external') {
+                } else if (event.action === 'select_external') {
+                    let ret = ziti.extAuthToken(token)
+                } else if (event.action === 'cannot_continue') {
+                } else if (event.action === 'prompt_totp') {
+                } else if (event.action === 'prompt_pin') {
+                } else {
+                }
+    
+            }
+
+            const cfgStr = JSON.stringify(cfg)
+    
+            let initResult = await ziti.init(cfgStr, onAuthEvent)              
+
+            return resolve( initResult );
+        });
+      } catch (e) {
+          reject(e);
+      }
+
+    });
+
+};
+
+exports.initExternalAuth = initExternalAuth;

package/lib/websocketClose.js

@@ -0,0 +1,31 @@
+/*
+Copyright NetFoundry Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+
+/**
+ * websocketClose()
+ *
+ * Close a Ziti WebSocket connection.
+ *
+ * @param {number} ws - The WebSocket handle returned from websocketConnect
+ * @returns {void}
+ */
+const websocketClose = (ws) => {
+    ziti.ziti_websocket_close(ws);
+};
+
+
+exports.websocketClose = websocketClose;

package/lib/websocketConnect.js

@@ -0,0 +1,54 @@
+/*
+Copyright NetFoundry Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+
+/**
+ * Default on_connect callback
+ */
+const defaultOnConnect = (ws) => {
+    console.log('websocketConnect: connected, ws:', ws);
+};
+
+/**
+ * Default on_data callback
+ */
+const defaultOnData = (data) => {
+    console.log('websocketConnect: data received, len:', data.len);
+};
+
+
+/**
+ * websocketConnect()
+ *
+ * Connect to a Ziti service via WebSocket.
+ *
+ * @param {string} url - The WebSocket URL (e.g., 'wss://service.ziti/path')
+ * @param {string[]} headers - Array of headers in "name:value" format
+ * @param {function} on_connect_cb - Callback invoked on connection. Receives the websocket handle.
+ * @param {function} on_data_cb - Callback invoked when data is received. Receives {len, data}.
+ * @returns {void}
+ */
+const websocketConnect = (url, headers, on_connect_cb, on_data_cb) => {
+
+    const connect_cb = (typeof on_connect_cb === 'function') ? on_connect_cb : defaultOnConnect;
+    const data_cb = (typeof on_data_cb === 'function') ? on_data_cb : defaultOnData;
+    const hdrs = Array.isArray(headers) ? headers : [];
+
+    ziti.ziti_websocket_connect(url, hdrs, connect_cb, data_cb);
+};
+
+
+exports.websocketConnect = websocketConnect;

package/lib/websocketPing.js

@@ -0,0 +1,31 @@
+/*
+Copyright NetFoundry Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+
+/**
+ * websocketPing()
+ *
+ * Send a ping frame on a Ziti WebSocket connection.
+ *
+ * @param {number} ws - The WebSocket handle returned from websocketConnect
+ * @returns {number} 0 on success, error code on failure
+ */
+const websocketPing = (ws) => {
+    return ziti.ziti_websocket_ping(ws);
+};
+
+
+exports.websocketPing = websocketPing;

package/lib/websocketWrite.js

@@ -0,0 +1,47 @@
+/*
+Copyright NetFoundry Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+
+/**
+ * Default on_write callback
+ */
+const defaultOnWrite = (result) => {
+    console.log('websocketWrite: write completed, status:', result.status);
+};
+
+
+/**
+ * websocketWrite()
+ *
+ * Write data to a Ziti WebSocket connection.
+ *
+ * @param {number} ws - The WebSocket handle returned from websocketConnect
+ * @param {Buffer} data - The data to send
+ * @param {function} on_write_cb - Callback invoked when write completes. Receives {ws, status}.
+ * @returns {void}
+ */
+const websocketWrite = (ws, data, on_write_cb) => {
+
+    const write_cb = (typeof on_write_cb === 'function') ? on_write_cb : defaultOnWrite;
+
+    // Ensure data is a Buffer
+    const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data);
+
+    ziti.ziti_websocket_write(ws, buffer, write_cb);
+};
+
+
+exports.websocketWrite = websocketWrite;

package/lib/ziti.js

@@ -161,14 +161,106 @@ exports.httpRequest       = require('./httpRequest').httpRequest;
  */
  exports.httpRequestEnd   = require('./httpRequestEnd').httpRequestEnd;
 
+/**
+ * Connect to a Ziti Service via WebSocket.
+ * @function websocketConnect
+ * @param {string} url - The WebSocket URL (e.g., 'wss://service.ziti/path')
+ * @param {string[]} headers - Array of headers in "name:value" format
+ * @param {onWebSocketConnectCallback} onConnect - Callback invoked on connection.
+ * @param {onWebSocketDataCallback} onData - Callback invoked when data is received.
+ * @returns {void} No return value.
+ */
+/**
+ * This callback is part of the `websocketConnect` API.
+ * @callback onWebSocketConnectCallback - Called when WebSocket connection is established.
+ * @param {number} ws - The WebSocket handle for use with websocketWrite.
+ * @returns {void} No return value.
+ */
+/**
+ * This callback is part of the `websocketConnect` API.
+ * @callback onWebSocketDataCallback - Called when data is received on the WebSocket.
+ * @param {object} data - The received data object.
+ * @param {number} data.len - Length of the data (negative indicates error/close).
+ * @param {Buffer} data.data - The received data buffer.
+ * @returns {void} No return value.
+ */
+exports.websocketConnect  = require('./websocketConnect').websocketConnect;
+
+/**
+ * Write data to a Ziti WebSocket connection.
+ * @function websocketWrite
+ * @param {number} ws - The WebSocket handle from websocketConnect.
+ * @param {Buffer} data - The data to send.
+ * @param {onWebSocketWriteCallback} onWrite - Callback invoked when write completes.
+ * @returns {void} No return value.
+ */
+/**
+ * This callback is part of the `websocketWrite` API.
+ * @callback onWebSocketWriteCallback - Called when the write operation completes.
+ * @param {object} result - The write result object.
+ * @param {number} result.ws - The WebSocket handle.
+ * @param {number} result.status - Write status (0 = success, negative = error).
+ * @returns {void} No return value.
+ */
+exports.websocketWrite    = require('./websocketWrite').websocketWrite;
+
+/**
+ * Close a Ziti WebSocket connection.
+ * @function websocketClose
+ * @param {number} ws - The WebSocket handle from websocketConnect.
+ * @returns {void} No return value.
+ */
+exports.websocketClose    = require('./websocketClose').websocketClose;
+
+/**
+ * Send a ping frame on a Ziti WebSocket connection.
+ * @function websocketPing
+ * @param {number} ws - The WebSocket handle from websocketConnect.
+ * @returns {number} 0 on success, error code on failure.
+ */
+exports.websocketPing     = require('./websocketPing').websocketPing;
+
+/**
+ * Provide an external JWT token for authentication.
+ *
+ * Use this function when external authentication is required (e.g., OIDC).
+ * The auth event callback provided to init() will indicate when external
+ * auth is needed along with the provider details.
+ *
+ * @function extAuthToken
+ * @param {string} jwtToken - The JWT token obtained from the external identity provider
+ * @returns {number} 0 on success, -22 (ZITI_INVALID_STATE) if context not initialized
+ * @throws {Error} If jwtToken is not a non-empty string
+ */
+exports.extAuthToken      = require('./extAuthToken').extAuthToken;
+
 /**
  * Initialize the Ziti session and authenticate with control plane.
  * @function init
  * @param {string} identityPath - File system path to the identity file.
- * @returns {number} A status value ranging from 0 to 255.
+ * @param {onAuthEventCallback} [onAuthEvent] - Optional callback for authentication events.
+ * @returns {Promise<void>} Resolves when initialization is complete.
+ */
+/**
+ * This callback is part of the `init` API.
+ * @callback onAuthEventCallback - Called when authentication events occur.
+ * @param {object} authEvent - The authentication event object.
+ * @param {string} authEvent.action - The action required (e.g., 'login_external', 'select_external', 'cannot_continue', 'prompt_totp', 'prompt_pin').
+ * @param {string} authEvent.type - The authentication type (e.g., 'oidc').
+ * @param {string} authEvent.detail - Additional details (e.g., the OIDC provider URL).
+ * @returns {void} No return value.
  */
 exports.init              = require('./init').init;
 
+/**
+ * Initialize external authentication with a Ziti controller.
+ * @function initExternalAuth
+ * @param {string} controllerHost - The hostname of the Ziti controller (e.g., "ctrl.example.com:1280")
+ * @param {onAuthEventCallback} onAuthEvent - Callback for authentication events.
+ * @returns {number} 0 on success, error code on failure
+ */
+exports.initExternalAuth  = require('./initExternalAuth').initExternalAuth;
+
 // Internal use only
 exports.listen            = require('./listen').listen;
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@openziti/ziti-sdk-nodejs",
   "description": "A NodeJS-based SDK for delivering secure applications over a Ziti Network",
-  "version": "0.28.1",
+  "version": "0.29.0",
   "main": "./lib/ziti",
   "scripts": {
     "build": "npm run build:configure && npm run build:make",
@@ -53,6 +53,7 @@
   },
   "dependencies": {
     "@mapbox/node-pre-gyp": "^2.0.3",
-    "bindings": "^1.5.0"
+    "bindings": "^1.5.0",
+    "segfault-handler": "^1.3.0"
   }
 }

package/tests/addon.test.js

@@ -8,6 +8,7 @@ suite("Ziti SDK Addon Tests", () => {
         assert(typeof ziti.ziti_sdk_version === "function", "ziti_sdk_version should be a function");
         assert(typeof ziti.enroll === "function", "ziti_enroll should be a function");
         assert(typeof ziti.setLogger === "function", "ziti_set_logger should be a function");
+        assert(typeof ziti.extAuthToken === "function", "ziti_ext_auth_token should be a function");
 
     })
     test("ziti_sdk_version test", () => {