Associated Article(s)

For more context on this SDK, you may be interested in this article concerning how to secure NodeJS applications

Supported platforms

The @openziti/ziti-sdk-nodejs module works with the following Node.js versions:

• v16.x
• v18.x
• v19.x
• v20.x
• v21.x
• v22.x
• v23.x

The @openziti/ziti-sdk-nodejs module works with the following architectures:

• amd64
• arm64

The @openziti/ziti-sdk-nodejs module works with the following Operating Systems:

• macos
• linux
• windows

Installing

NPM

npm i @openziti/ziti-sdk-nodejs

or Yarn

yarn add @openziti/ziti-sdk-nodejs

Special note on previous package:

On June 7, 2020 @openziti/[email protected] was released. Older, unscoped versions that are not part of the @openziti org are deprecated and only @openziti/ziti-sdk-nodejs will see updates going forward. To upgrade to the new package do:

npm uninstall ziti-sdk-nodejs --save
npm install @openziti/ziti-sdk-nodejs --save

Usage

Note: the module must be installed before use.

ESM example (client-side)

import ziti from '@openziti/ziti-sdk-nodejs';

// Somehow provide path to identity file, e.g. via env var
const zitiIdentityFile  = process.env.ZITI_IDENTITY_FILE;
// Authenticate ourselves onto the Ziti network
await ziti.init( zitiIdentityFile ).catch(( err ) => { /* probably exit */ });

const on_resp_data = ( obj ) => {
    console.log(`response is: ${obj.body.toString('utf8')}`);
};

// Perform an HTTP GET request to a dark OpenZiti web service
ziti.httpRequest(
  'myDarkWebService',            // OpenZiti Service name or HTTP origin part of the URL
  undefined,                     // schemeHostPort parm is mutually-exclusive with serviceName parm
  'GET',
  '/',                           // path part of the URL including query params
  ['Accept: application/json' ], // headers
  undefined,                     // optional on_req cb 
  undefined,                     // optional on_req_data cb
  on_resp_data                   // optional on_resp_data cb
);

ESM example (server-side ExpressJS)

import ziti from '@openziti/ziti-sdk-nodejs';
import express from 'express';
let app = ziti.express( express, zitiServiceName );
app.listen(ignored, function() { ... }

/**

That's right.

With only a single-line code change (the ziti.express call), your web server is now capable
of being invisible to malicious attackers on the internet, and only accessible to your 
trusted remote users.

Nothing else in your existing ExpressJS web server code needs to change!

Existing routing, middleware, etc., all operates the same as it always did... 
but now you enjoy the comfort of knowing that if a connection comes in, it is from 
a trusted identity on the client side.

No malicious actors can see your dark web server, and thus, no malicious actors can attack it.

*/

CJS example (client-side)

var ziti = require('@openziti/ziti-sdk-nodejs');

const ziti_init = async (identity) => {
    return new Promise((resolve) => {
        ziti.ziti_init(identity, () => {
            resolve();
        });
    });
};

const ziti_service_available = (service) => {
    return new Promise((resolve) => {
        ziti.ziti_service_available(service, (status) => {
            resolve(status);
        });
    });
};

function ziti_dial(service) {
    return new Promise((resolve, reject) => {
        ziti.ziti_dial(
            service,
            (conn) => {
                resolve(conn);
            },
            (data) => {
                // Do something with data...
            },
        );
    });
}

const ziti_write = (conn, data) => {
    return new Promise((resolve) => {
        ziti.ziti_write(conn, data, () => {
            resolve();
        });
    });
};

(async () => {

    await ziti_init(LOCATION_OF_IDENTITY_FILE);

    let status = await ziti_service_available(YOUR_SERVICE_NAME);

    if (status === 0) {

        const conn = await ziti_dial(YOUR_SERVICE_NAME);

        let data = SOME_KIND_OF_DATA;

        let buffer = Buffer.from(data);

        await ziti_write(conn, buffer);

        ...etc
    }

})();

API Reference

For doc concerning API's contained in this SDK, you may be interested in this SDK API Reference

Getting Help

Please use these community resources for getting help. We use GitHub issues for tracking bugs and feature requests and have limited bandwidth to address them.

• Read the docs
• Participate in discussion on Discourse

Building from source on MacOS

git clone https://github.com/microsoft/vcpkg.git
./vcpkg/bootstrap-vcpkg.sh
export VCPKG_ROOT=`pwd`/vcpkg
brew install cmake
brew install ninja
brew install pkg-config
git clone https://github.com/openziti/ziti-sdk-nodejs.git
cd ziti-sdk-nodejs
npm run build

Copyright© NetFoundry, Inc.