@holo-host/chaperone v9.0.0

Holo Chaperone

Chaperone is Holo's secure web-zone for managing access to an Agent's identity and connections. A hApp developer will use the Holo Hosting Web SDK which makes calls to Chaperone over our Cross-origin Message Bus (COMB).

The API that is exposed to a hApp developer is simple to minimize integration requirements and limit the number of access points that need to be audited for potential leaks.

Architecture

Chaperone must be able to communicate with Envoy or Conductor based on the current mode.

• COMB - Works the same in all scenarios

Modes

Chaperone.PRODUCT

This mode is for production.

Implements

• Connection to Resolver - Required to establish a connection
• Key Management - Chaperone manages the Agent keys and signatures must be sent with every request.
• RPC WebSocket - This connection is to Envoy which needs additional context for each request (wrapped payload).

Chaperone.DEVELOP

This mode is for the development of Chaperone with envoy. It allows a contributor to bypass some external dependencies such as Resolver, and means you can specify a holoport to use as the host.

Implements

• Key Management - Conductor manages the Agent keys.
• RPC WebSocket - This connection is to Envoy but the Host connection must be specified at initialization because Resolver is not used.

Chaperone.HCC

This mode is for hApp developers and is used by chaperone-server. In this scenario the agent keys are controlled by Conductor and therefore it does not utilize the Key Management code.

Implements

• RPC WebSocket - This connection is directly to Conductor and will only accept the unwrapped payload.

When configuring Conductor, Chaperone is assuming these conventions:

• anonymous/read-only installed app ID <hha_hash>
• Hosted user installed app ID <hha_hash>:<agent_id>

  PLEASE NOTE: The hha_hash referenced in Chaperone represents the header hash of the app within the holo-hosting-app dht. It is not the DNA hash of the holo-hosting-app (hha). You may find more information about the rsm pattern for hosted IDs here.

Usage

Javascript API

API Reference

Running chaperone server locally

npm install -D @holo-host/chaperone
npx chaperone-server --config <configruation>

Example config for HCC mode

{
    "mode": "Chaperone.HCC",
    "app_id": "uhCkkmrkoAHPVf_eufG7eC5fm6QKrW5pPMoktvG5LOC0SnJ4vV1Uv",
    "log_level": true,
    "connection": {
      "secure": false,
      "host": "localhost",
      "port": 42233,
      "path": "/"
    },
    "web_user_legend": {
        "bob@holo.host": "uhCAkkeIowX20hXW+9wMyh0tQY5Y73RybHi1BdpKdIdbD26Dl/xwq",
        "alice@holo.host": "uhCAkTFYCB48/Bx/QvKQPVSuXAV8sLHKJXrh6ZS8YVe2MdsvSgc7q",
    },
    "hcc_admin_port": 4444,
}

Example config for DEVELOP mode

{
    "mode": "Chaperone.DEVELOP",
    "app_id": "uhCkkmrkoAHPVf_eufG7eC5fm6QKrW5pPMoktvG5LOC0SnJ4vV1Uv",
    "log_level": true,
    "connection": {
      "secure": true,
      "host": "15ro3eddkk4bvjg6lc9p1yditiwfl89uo9ow7eiqdyioaan70x.holohost.net",
      "port": 42233,
      "path": "/hosting/" // second trailing slash is necessary
    },
    "web_user_legend": {
        "bob@holo.host": "uhCAkkeIowX20hXW+9wMyh0tQY5Y73RybHi1BdpKdIdbD26Dl/xwq",
        "alice@holo.host": "uhCAkTFYCB48/Bx/QvKQPVSuXAV8sLHKJXrh6ZS8YVe2MdsvSgc7q",
    },
}

• mode - one of "Chaperone.HCC" (default), "Chaperone.DEVELOP", or "Chaperone.PRODUCT"
• app_id - It should correspond with the installed_app_id of your app in the conductor. In DEVELOP and PRODUCT mode, this will be the HHA hash of your app.
• log_level - true/false for on/off as there are currently no configured levels
• connections.secure - true/false for using wss or ws. Needs to be true in DEVELOP and PRODUCT.
• connections.host - defaults to window.location.hostname
• connections.port - defaults to 4656
• connections.path - defaults to /. Should be /hosting/ (note the trailing slash) for DEVELOP and PRODUCT
• web_user_legend - (optional) A map used to hard code an agent's public key. This is particularly useful/necessary in HCC mode.
  • Key: either a seed value (normally stored in localstorage to remember a login) or user email
  • Value: agent ID (public key prefixed by uhCAK). These public keys should correspond with agents in the conductor.
• hcc_admin_port - (optional) In HCC mode, Chaperone can establish and admin interface websocket connection to Holochain using this port in order to determine the agent public key associated with the installed app. If you wanted to make zome calls without this feature, you would need to query the agent key in your installed holochain app manually, and specify a web_user_legend that contained it.

Contributors

See ./CONTRIBUTING.md