Chaperone

@holo-host/chaperone~ Chaperone

new Chaperone(port)

Chaperone manages the connection(s), keys, and iframe message bus for a hApp user.

Parameters:
Name Type Description
port number

Set port property (default: 4656)
Properties:
Name Type Description
COMB object

Local access to COMB library
seed buffer

32 bytes used for KeyPair seed
keys object

KeyManager instance
agent_id string

hcs0 encoding of public key
anonymous boolean

True when this.seed is random bytes
instance_prefix string

Used to guarantee instance IDs are unique (HHA ID for Envoy / hApp ID for Conductor)
hha_hash string

Holo Hosting App registered hApp Hash
conn object

Current RPC WebSocket instance
host string

WebSocket server host
port number

WebSocket server port
opened boolean

True when WebSocket is in readyState === OPEN
wormhole_ready boolean

True when the wormhole listener has been established
wormhole_listeners object

Internal map of promises waiting for wormhole requests
Source:
Example
const chaperone = new Chaperone();
await chaperone.ready();
chaperone.instance_prefix = "some_instance_prefix";

Methods

agentId() → {string}

Get the Agent ID of the signed in user. Returns "anonymous" if user is not signed in.

Source:
Example
let agent_id = chaperone.agentId();

(async) callZomeFunction(dna_alias, zome_name, function_name, args) → {*}

Call a zome function on the connected Host with given parameters. instance_id is derived by combining this.agent_id, this.instance_prefix, and the given dna_alias. When signed in, the Agent ID and payload signature will be added to every request.

Parameters:
Name Type Description
dna_alias string

DNA alias (used for instance ID)
zome_name string

Zome name
function_name string

Zome function name
args object

Function arguments
Source:
Example
let data = await chaperone.callZomeFunction( "holofuel", "transactions", "list_pending" );

(async) close() → {void}

Shutdown any connections and change this.opened to false.

Source:
Example
await chaperone.close();
chaperone.opened === false

(async, private) connect(timeout) → {void}

Get a valid Host for a given hostname or hApp ID (and Agent ID if signed in), and then create a WebSocket connection to that host.

Parameters:
Name Type Description
timeout number

Timeout for WebSocket connection
Source:
Example
await this.connect( 5000 );
chaperone.opened === true

(async, private) disconnect() → {void}

Close current connection.

Source:
Example
await this.disconnect();
chaperone.opened === false

getSignature(data) → {string}

Get the base64 encoded signature for a given data object. Converts objects using JSON.stringify when given data is not a string.

Parameters:
Name Type Description
data string | object

Data to be signed
Source:
Example
let signature = chaperone.getSignature( { "email": "someone@example.com" );

(async, private) handleWormholeRequests() → {void}

Set up wormhole handler for RPC WebSocket connection. Once complete, this.wormhole_ready will be set to true.

Source:

(private) happHost() → {string}

Get the Host address of the parent window (hApp UI).

Source:
Example
let happ_host = this.happHost();

(async, private) init(timeout) → {void}

Create an anonymous key pair. Select a host and make a WebSocket connection. Once the WebSocket is in readyState = OPEN, register and subscribe for wormhole requests which are automatically signed and returned to host. By the time init is returns, the connection and wormhole are ready for use.

Parameters:
Name Type Description
timeout number

Timeout for WebSocket connection
Source:
Example
await this.init( 5000 );
chaperone.opened         === true
chaperone.wormhole_ready === true
chaperone.anonymous      === true

(async) ready(timeout) → {this}

Async method that returns when the WebSocket and wormhole signing is setup.

Parameters:
Name Type Description
timeout number

Unused timeout
Source:
Example
try {
    await chaperone.ready( 5000 );
} catch ( err ) {
    // Timeout
}

(async) signIn(email, password) → {void}

Create a derived seed from the given credentials and re-initialize connection process. Returns once the new WebSocket connection is in readyState = OPEN.

Parameters:
Name Type Description
email string

Agent's email address
password string

Agent's password
Source:
Example
await chaperone.signIn( "someone@example.com" , "Passw0rd!" );
// chaperone is now connected to a host for signed in user
chaperone.anonymous === false

websocket() → {WebSocket}

Get the WebSocket instance for our current connection. RPC WebSocket is a class that wraps the real WebSocket connection. Unfortunately, the rpc-websockets module stores the socket differently on web vs node.js implementations.

Source:
Example
let ws = chaperone.websocket();
ws.constructor.name === "WebSocket";

(async) wormholeRequest(id) → {string}

Get the signature of a specific wormhole request. Returns after wormhole response.

NOTE: The original use case for this method is unit testing. It may not be useful outside of the testing context.

Parameters:
Name Type Description
id number

Wormhole request ID
Source:
Example
let [signature,data] = chaperone.wormholeRequest( 0 );
// Signature is equivalent to
signature === chaperone.getSignature( data );