Node.js API Reference

Overview

This page documents the Node.js accessor API: constructors, lifecycle methods, input ports, output handlers, runtime parameters, and helper methods.

The Node.js API is implemented in entity/node/accessors/. The four classes are:

• SecureCommClient — secure TCP client
• SecureCommServer — secure TCP server
• SecurePublisher — encrypted MQTT/UDP publisher
• SecureSubscriber — encrypted MQTT/UDP subscriber

SecureCommClient

const SecureCommClient = require('../accessors/SecureCommClient');

Constructor

const client = new SecureCommClient(configFilePath);

Loads an entity config (JSON with .config extension) from configFilePath. Generated configs live under entity/node/example_entities/configs/.

initialize()

client.initialize();

Sets up distribution-key state, output slots, and output handlers. Does not open a connection.

provideInput(port, value)

Port	Value type	Behavior
'serverHostPort'	{host, port}	Requests a session key and performs the SST handshake with the target.
'serverHostPort'	null	Closes the current secure client socket.
'toSend'	Buffer	Encrypts and sends data over the active connection.

client.provideInput('serverHostPort', { host: 'localhost', port: 21100 });
client.provideInput('toSend', Buffer.from('hello'));
client.provideInput('serverHostPort', null);

provideInputResource(port, value, resourceName)

client.provideInputResource('serverHostPort', { host: 'localhost', port: 21100 }, 'myResource');

Variant of provideInput that includes a resource name in the session key purpose, enabling fine-grained per-resource access control.

setOutputHandler(key, handler)

client.setOutputHandler('connected', (connected) => {});
client.setOutputHandler('received', (data) => {});
client.setOutputHandler('error', (message) => {});
client.setOutputHandler('privilege', (result) => {});

Output handler keys:

Key	Handler value	When fired
'connected'	boolean	true when handshake completes; false when connection closes.
'received'	Buffer	Decrypted data received from the server.
'error'	string	Error message (auth failure, handshake error, migration, etc.).
'privilege'	object	Result of a DelegationGrant or DelegationRevoke operation.

latestOutput(key)

const data = client.latestOutput('received');
const isConnected = client.latestOutput('connected');

Returns the most recently stored value for a given output key.

setParameter(key, value)

client.setParameter('numKeysPerRequest', 5);
client.setParameter('migrationEnabled', true);

Runtime parameters:

Parameter	Default	Meaning
numKeysPerRequest	1	Session keys requested per operation.
migrationEnabled	false	Enables automatic Auth failover.
authFailureThreshold	3	Auth failures before migration is triggered.
migrationFailureThreshold	3	Migration failures before rotating targets.
keyId	—	Specific session key ID for experiment paths.

Helper methods

Method	Returns	Description
getTargetServerInfoList()	array	Returns configured target servers: [{name, host, port}, ...].
getEntityInfo()	object	Returns entity metadata from the config.
showKeys()	string	Formatted string of distribution key and cached session keys.
showSocket()	string	Formatted string of current socket state.
getSessionKeysForCaching(numKeys)	void	Requests {group: 'Servers'} session keys for future connections.
getSessionKeyIdForGrantAccess(numKeys, trustLevel)	void	Requests a session key ID for a delegation grant; prints as JSON to stdout. trustLevel can be 'HighTrustAgents', 'MediumTrustAgents', or 'LowTrustAgents'.
getSessionKeysForGrantAccess(keyId)	void	Retrieves full session keys for keyId; prints as JSON to stdout and exits. Used by agent entities.
getSessionKeysForWebsite(keyId)	void	Like getSessionKeysForGrantAccess but also includes the owner group in the output, for trust-level verification. Used by website entities.
performPrivilege(type, subject, object, validity)	void	Sends a delegation request to Auth. type: 'DelegationGrant' or 'DelegationRevoke'. validity: e.g. '1*day' or null. Fires the 'privilege' handler on completion.
migrateToTrustedAuth()	void	Manually triggers migration to the next Auth in migrationInfo.
setEntityInfo(key, value)	void	Mutates entity config at runtime.

SecureCommServer

const SecureCommServer = require('../accessors/SecureCommServer');

Constructor

const server = new SecureCommServer(configFilePath);

Loads a server entity config. Server configs include a listeningServerInfo field with the port to bind.

initialize()

server.initialize();

Sets up distribution-key state, output handlers, and starts the secure TCP listener on the configured port.

provideInput(port, value)

Port	Value type	Behavior
'toSend'	{data: Buffer, id: number}	Encrypts and sends data to the client identified by id.
'toSend'	{data: Buffer, id: null}	Broadcasts data to all connected clients.
'toSend'	null	Closes all client connections.

setOutputHandler(key, handler)

server.setOutputHandler('listening', (port) => {});
server.setOutputHandler('connection', (info) => {});
server.setOutputHandler('received', (received) => {});
server.setOutputHandler('error', (info) => {});

Output handler keys:

Key	Handler value	When fired
'listening'	number	Port the server is listening on, after initialize().
'connection'	string	Human-readable connection/disconnection event message.
'received'	{data: Buffer, id: number}	Decrypted data from a client socket identified by id.
'receivedID'	{data: Buffer, id: number}	Alias for 'received'.
'error'	string	Error details including socket ID and description.

latestOutput(key)

Returns the most recently stored value for a given output key.

setParameter(key, value)

Parameter	Meaning
migrationEnabled	Enables Auth failover.
authFailureThreshold	Auth failures before migration.
migrationFailureThreshold	Migration failures before rotating targets.

Helper methods

Method	Returns	Description
getEntityInfo()	object	Returns entity metadata from the config.
showKeys()	string	Formatted string of distribution key and cached session keys.
showSocket()	string	Formatted string of all connected client sockets.
getSessionKeysForFutureClients(numKeys)	void	Pre-requests {cachedKeys: 101} session keys for upcoming client handshakes.
getSessionKeysForPublish(numKeys)	void	Requests {pubTopic: 'Ptopic'} session keys for publish scenarios.
migrateToTrustedAuth()	void	Manually triggers Auth migration.
setEntityInfo(key, value)	void	Mutates entity config at runtime.

SecurePublisher

const SecurePublisher = require('../accessors/SecurePublisher');

Constructor and initialization

const pub = new SecurePublisher(configFilePath);
pub.setParameter('numKeysPerRequest', 1);
pub.setParameter('topic', 'Ptopic');
pub.initialize();

initialize() connects to the MQTT broker (TCP) or creates a UDP broadcast socket, then requests session keys.

provideInput('toPublish', value)

pub.provideInput('toPublish', Buffer.from('payload'));

Encrypts and publishes the message using the current session key. Increments the sequence number automatically.

setOutputHandler output keys

Key	Handler value	When fired
'connection'	string	Connection established.
'error'	string	Error occurred.
'ready'	string	Session keys have been obtained; publisher is ready.

Parameters

Parameter	Default	Meaning
numKeysPerRequest	1	Session keys to request from Auth.
topic	null	MQTT publish topic (TCP mode).

Protocol support

• TCP (distProtocol: 'TCP'): publishes encrypted data to an MQTT broker.
• UDP (distProtocol: 'UDP'): broadcasts encrypted data to 255.255.255.255:8088.

SecureSubscriber

const SecureSubscriber = require('../accessors/SecureSubscriber');

Constructor and initialization

const sub = new SecureSubscriber(configFilePath);
sub.initialize();

initialize() sets up output handlers but does not start subscribing until provideInput('subscribe', ...) is called.

provideInput(port, value)

Port	Value	Behavior
'subscribe'	string or port number	Subscribes to the given MQTT topic or UDP port.
'unsubscribe'	string or port number	Unsubscribes from the given topic or port.

setOutputHandler output keys

Key	Handler value	When fired
'subscription'	string	Subscribe/unsubscribe action completed.
'received'	{data: Buffer, topic: string}	Decrypted message arrived.
'connection'	string	Connection established.
'error'	string	Error occurred.

Protocol support

• TCP: subscribes to an MQTT topic (e.g., 'Ptopic').
• UDP: listens on the specified port for broadcast messages.

Config fields

Node accessors read JSON config files generated by generateAll.sh. Relevant fields:

Field	Meaning
entityInfo.name	Entity name registered with Auth.
entityInfo.group	Entity group (e.g., Clients, Servers).
entityInfo.distProtocol	TCP or UDP.
entityInfo.connectionTimeout	Timeout for connections (ms).
entityInfo.usePermanentDistKey	Use pre-shared symmetric distribution key.
authInfo.id	Auth ID.
authInfo.host	Auth hostname.
authInfo.port	Auth port.
authInfo.publicKey	Auth public key/certificate.
cryptoInfo.distributionCryptoSpec	Distribution channel crypto spec.
cryptoInfo.sessionCryptoSpec	Session key crypto spec.
listeningServerInfo.port	Listening port for server entities.
targetServerInfoList	[{name, host, port}] — target servers for client entities.
migrationInfo	[{host, port}] — alternate Auth endpoints for failover.