https://github.com/fireblocks/fireblocks-agent
Fireblocks on-prem agent for managing external keys
https://github.com/fireblocks/fireblocks-agent
Last synced: about 1 month ago
JSON representation
Fireblocks on-prem agent for managing external keys
- Host: GitHub
- URL: https://github.com/fireblocks/fireblocks-agent
- Owner: fireblocks
- Created: 2023-12-28T09:59:27.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-24T19:38:29.000Z (about 2 months ago)
- Last Synced: 2025-03-24T20:32:48.280Z (about 2 months ago)
- Language: TypeScript
- Size: 2.65 MB
- Stars: 8
- Watchers: 2
- Forks: 2
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
[](https://github.com/fireblocks/fireblocks-agent/actions/workflows/node.js.yml)
# Welcome to Fireblocks Agent
Fireblocks Agent is an open-source on-prem service written in Typescript which is responsible for receiving new messages to sign from Fireblocks, relay these messages to the client's HSM and return the signed result back to Fireblocks.
# Develop (Run Locally)
### Prerequisites
- Make sure you have nvm on your machine. To check, run `nvm` in a terminal.
- To install `nvm`:
- On mac run `brew install nvm`
- Linux, follow these [instructions](https://github.com/nvm-sh/nvm?tab=readme-ov-file#installing-and-updating)
### Installation
- `git clone https://github.com/fireblocks/fireblocks-agent.git`
- `cd fireblocks-agent`
- `nvm use`
- install dependencies `npm i`
### Running
- Build and run example customer server docker:
- `cd examples/server`
- `npm run build:docker`
- `npm run start:docker`
- Configure and run Fireblocks agent:
- Copy `.env.prod` and name it `.env.{env-name}` (e.g. `.env.test`)
- Edit your newly created `.env.{env-name}` file with the right configuration
- Build the Fireblocks agent:
- `npm run build`
- Start the Fireblocks agent with your desired environment:
- `npm run start --env=env-name`
### Fireblocks Agent Environment Variables
The Fireblocks agent expect a configuration file (for production it's called `.env.prod`) with several parameters:
* `MOBILE_GATEWAY_URL` - In production this value should be `https://mobile-api.fireblocks.io`
* `CUSTOMER_SERVER_URL` - The client's custom server url
* `CUSTOMER_SERVER_PULL_CADENCE_MS` - Cadence of pulling messages status
* `CUSTOMER_SERVER_AUTHORIZATION` - If exists, the Fireblocks agent will send its value on the `Authorization` header for each request. The client can use it for authorizing the fireblocks agent or keep track on which agent is calling it
* `SSL_CERT_PATH` - If exists, a path to a self-signed SSL certificate which will be used to validate the server certificate
# About the Fireblocks Key Link Workspace
## Actors
The Fireblocks Key Link workspace consists of several components (aka actors). Each with its own responsibilities.
* Console - Fireblocks web console. [Link](https://console.fireblocks.io/v2/)
* Mobile App - Fireblocks mobile app.
* Mobile API Gateway - Fireblocks REST API Server. The Fireblocks agent communicates with this server in the registration flow and for receiving new messages.
* Developer API - Fireblocks back office server for workspace setup and configuration.
* Fireblocks Agent - An on-prem service written in Typescript which is responsible for receiving new messages to sign from Fireblocks, relay these messages to the client's HSM and return the signed result back to Fireblocks.
* Customer Server - The client's own server which receives messages to sign from the Fireblocks agent. Sign them via the client's HSM and provide the Fireblocks agent with the signed messages.
* HSM component - The actual HSM implementation. Can be on prem or a cloud based HSM, or a different Key Management System.
## About the Customer Server
The customer server is a component that should be written by the client according to the client's connection to the HSM component. The server is expected to implement the following [OpenAPI spec](api/customer-server.api.yml).
In general, it should support signing messages according to `ECDSA` and `EdDSA` algorithms and return the status for given messages.
We provide an example of such a server in `examples/server` with an integration to a software implementation of an HSM called [softHSM](https://www.opendnssec.org/softhsm/)
The entry point for the server can be found [here](examples/server/src/server.ts)
## Main Flows
### Create a New Fireblocks Agent API User
### Pair the Fireblocks Agent Device
### Add a Validator Key
This procedure should happen once. Fireblocks will need a validator key to approve new signing keys. This flow is done via the Fireblocks sdk and not via this program.
### Add Signing Keys
Each signing key should be first converted into a certificate which should be signed by an active validator key. The signed certificates are then regsitered to Fireblocks via the API or the Console.
### Fireblocks Agent & Customer Server with HSM - Main Flow
