{"id":22609022,"url":"https://github.com/bitfinexcom/grenache-nodejs-ws-tls","last_synced_at":"2025-04-11T06:20:25.683Z","repository":{"id":57253985,"uuid":"92386356","full_name":"bitfinexcom/grenache-nodejs-ws-tls","owner":"bitfinexcom","description":null,"archived":false,"fork":false,"pushed_at":"2021-11-17T22:09:46.000Z","size":65,"stargazers_count":2,"open_issues_count":0,"forks_count":8,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-18T09:52:08.351Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitfinexcom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-05-25T09:15:44.000Z","updated_at":"2022-03-09T07:39:16.000Z","dependencies_parsed_at":"2022-08-31T09:01:54.696Z","dependency_job_id":null,"html_url":"https://github.com/bitfinexcom/grenache-nodejs-ws-tls","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitfinexcom%2Fgrenache-nodejs-ws-tls","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitfinexcom%2Fgrenache-nodejs-ws-tls/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitfinexcom%2Fgrenache-nodejs-ws-tls/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitfinexcom%2Fgrenache-nodejs-ws-tls/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitfinexcom","download_url":"https://codeload.github.com/bitfinexcom/grenache-nodejs-ws-tls/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248352218,"owners_count":21089403,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-08T15:10:38.718Z","updated_at":"2025-04-11T06:20:25.665Z","avatar_url":"https://github.com/bitfinexcom.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# grenache-nodejs-ws-tls\n\n\u003cimg src=\"logo.png\" width=\"15%\" /\u003e\n\n\n## deprecated! grenache-nodejs-ws-tls is part of [grenache-nodejs-ws](https://github.com/bitfinexcom/grenache-nodejs-ws) now.\n\n[grenache-nodejs-ws](https://github.com/bitfinexcom/grenache-nodejs-ws) with TLS support and optional payload validation based on client certificate.\n\nGrenache is a micro-framework for connecting microservices. Its simple and optimized for performance.\n\nInternally, Grenache uses Distributed Hash Tables (DHT, known from Bittorrent) for Peer to Peer connections. You can find more details how Grenche internally works at the [Main Project Homepage](https://github.com/bitfinexcom/grenache).\n\n  - [Currently Supported](#currently-supported)\n  - [Example](#example)\n  - [API](#api)\n\n## Currently Supported\n\n```\nPeerRPCClient\nPeerRPCServer\n```\n\n## Example\n\nThis RPC Server example announces a service called\n`rpc_whitelist_service` on the overlay network. When a client tries to\nconnect, we check on the serverside if the certificate fingerprint\nmatches the list of clients that we have whitelisted for connections,\nusing [the verifyClient callback](https://github.com/websockets/ws/blob/62cd03ea3705123136c20eedac1b57559d8ea542/doc/ws.md#new-websocketserveroptions-callback).\n\nIn case of a matching fingerprint, we establish the Websocket\nconnection.\n\nThe certificate data is also passed to the request handlers of the\nserver. That allows us to further define permissions for each client.\n\nThe fingerprint allows us to verify that just certain clients are\nallowed to run a specific action. In the example the client is allowed\nto run the `ping` command, but is not allowed to execute the action\n`deleteHarddisk`.\n\nBehind the scenes the DHT is asked for the IP of the server and then\nthe request is done as Peer-to-Peer request via Websockets.\n\n**Server:**\n\n```js\nconst Link = require('grenache-nodejs-link')\n\nconst link = new Link({\n  grape: 'http://127.0.0.1:30001'\n})\nlink.start()\n\n// this function is testing the cert before the ws connection\n// with the client is established.\nconst VALID_FINGERPRINTS = [\n  '22:48:11:0C:56:E7:49:2B:E9:20:2D:CE:D6:B0:7D:64:F2:32:C8:4B'\n]\n\nfunction verifyClient (info, cb) {\n  const cert = info.req.socket.getPeerCertificate()\n\n  if (VALID_FINGERPRINTS.indexOf(cert.fingerprint) !== -1) {\n    return cb(true)\n  }\n\n  return cb(false, 401, 'Forbidden')\n}\n\n// bootstrap our server\nconst opts = {\n  secure: {\n    key: fs.readFileSync(path.join(__dirname, 'certs', 'server-key.pem')),\n    cert: fs.readFileSync(path.join(__dirname, 'certs', 'server-crt.pem')),\n    ca: fs.readFileSync(path.join(__dirname, 'certs', 'ca-crt.pem')),\n    requestCert: true,\n    rejectUnauthorized: false, // take care, can be dangerous in production!\n    verifyClient: verifyClient\n  }\n}\nconst peer = new PeerRPCServer(\n  link,\n  opts\n)\npeer.init()\n\nconst service = peer.transport('server')\nservice.listen(1337)\n\nsetInterval(function () {\n  link.announce('rpc_whitelist_service', service.port, {})\n}, 1000)\n\n// this function is used to whitelist certain actions based on\n// the fingerprint after the tls ws connection has established\n// nobody is allowed to delete the harddisk, but one client is\n// allowed to perform the ping action\nconst permissions = {\n  deleteHarddisk: [],\n  ping: [\n    '22:48:11:0C:56:E7:49:2B:E9:20:2D:CE:D6:B0:7D:64:F2:32:C8:4B'\n  ]\n}\n\nfunction isAllowedToPerformAction (action, fingerprint) {\n  if (!permissions[action]) {\n    return false\n  }\n\n  if (permissions[action].indexOf(fingerprint) !== -1) {\n    return true\n  }\n\n  return false\n}\n\n// request handler which checks if the client is allowed to perform the\n// current action. uses a whitelist and certificate fingerprints\nservice.on('request', (rid, key, payload, handler, cert) =\u003e {\n  if (isAllowedToPerformAction(payload.action, cert.fingerprint)) {\n    handler.reply(null, payload.action + ' action is allowed for this client')\n    return\n  }\n\n  handler.reply(new Error('forbidden'))\n})\n```\n\n**Client:**\n\n```js\nconst Link = require('grenache-nodejs-link')\nconst link = new Link({\n  grape: 'http://127.0.0.1:30001'\n})\n\nlink.start()\n\nconst secure = {\n  key: fs.readFileSync(path.join(__dirname, 'certs', 'client1-key.pem')),\n  cert: fs.readFileSync(path.join(__dirname, 'certs', 'client1-crt.pem')),\n  ca: fs.readFileSync(path.join(__dirname, 'certs', 'ca-crt.pem')),\n  rejectUnauthorized: false // take care, can be dangerous in production!\n}\n\nconst peer = new PeerRPCClient(\n  link,\n  { secure: secure }\n)\n\npeer.init()\n\nlink.on('connect', () =\u003e {\n  peer.request('rpc_whitelist_service', { action: 'ping' }, { timeout: 10000 }, (err, data) =\u003e {\n    console.log(err, data) // logs: null 'ping action is allowed for this client'\n  })\n\n  // errors with forbidden error\n  peer.request('rpc_whitelist_service', { action: 'deleteHarddisk' }, { timeout: 10000 }, (err, data) =\u003e {\n    console.log(err, data) // logs: Error: forbidden\n  })\n})\n```\n\n[Server Code](https://github.com/bitfinexcom/grenache-nodejs-ws-tls/tree/master/examples/rpc_cert_whitelist_server.js)\n\u003cbr/\u003e\n[Client Code](https://github.com/bitfinexcom/grenache-nodejs-ws-tls/tree/master/examples/rpc_cert_whitelist_client.js)\n\n\n## API\n\n### Class: PeerRPCServer\n\n#### Event: 'request'\n\nEmitted when a request from a RPC client is received.\n\n  - `rid` unique request id\n  - `key` name of the service\n  - `payload` Payload sent by client\n  - `handler` Handler object, used to reply to a client.\n\n```js\nservice.on('request', (rid, key, payload, handler) =\u003e {\n  handler.reply(null, 'world')\n})\n```\n\n#### new PeerRPCServer(link, [options])\n\n  - `link` \u0026lt;Object\u0026gt; Instance of a [Link Class](#new-linkoptions)\n  - `options` \u0026lt;Object\u0026gt;\n    - `secure` \u0026lt;Object\u0026gt; TLS options\n      - `key` \u0026lt;Buffer\u0026gt; Key file content\n      - `cert` \u0026lt;Buffer\u0026gt; Cert file content\n      - `ca` \u0026lt;Buffer\u0026gt; Ca file content\n      - `rejectUnauthorized` \u0026lt;Boolean\u0026gt; Reject IPs / Hostnames not in cert's list\n      - `requestCert` \u0026lt;Boolean\u0026gt; Request a certificate from a connecting client\n      - `verifyClient` \u0026lt;Function\u0026gt; Function to verify connecting client before Websocket connection is established.\n\nCreates a new instance of a `PeerRPCServer`, which connects to the DHT\nusing the passed `link`.\n\n#### peer.init()\n\nSets the peer active. Must get called before we get a transport\nto set up a server.\n\n#### peer.transport('server')\n\nMust get called after the peer is active. Sets peer into server-\nmode.\n\n#### peer.listen(port)\n\nLets the `PeerRPCServer` listen on the desired `port`. The port is\nstored in the DHT.\n\n#### peer.port\n\nPort of the server (set by `listen(port)`).\n\n\n### Class: PeerRPCClient\n\n#### new PeerRPCClient(link, [options])\n\n  - `link` \u0026lt;Object\u0026gt; Instance of a [Link Class](#new-linkoptions)\n  - `options` \u0026lt;Object\u0026gt;\n    - `maxActiveKeyDests` \u0026lt;Number\u0026gt;\n    - `maxActiveDestTransports` \u0026lt;Number\u0026gt;\n    - `secure`: \u0026lt;Object\u0026gt; TLS options\n      - `key` \u0026lt;Buffer\u0026gt; Key file content\n      - `cert` \u0026lt;Buffer\u0026gt; Cert file content\n      - `ca` \u0026lt;Buffer\u0026gt; Ca file content\n      - `rejectUnauthorized` \u0026lt;Boolean\u0026gt; Reject IPs / Hostnames not in cert's list\n\nCreates a new instance of a `PeerRPCClient`, which connects to the DHT\nusing the passed `link`.\n\nA PeerRPCClient can communicate with multiple Servers and map work items over them.\nWith `maxActiveKeyDests` you can limit the maximum amount of destinations.\nAdditionally, you can limit the amount of transports with `maxActiveDestTransports`.\n\n#### peer.init()\n\nSets the peer active. Must get called before we start to make requests.\n\n#### peer.map(name, payload, [options], callback)\n  - `name` \u0026lt;String\u0026gt; Name of the service to address\n  - `payload` \u0026lt;String\u0026gt; Payload to send\n  - `options` \u0026lt;Object\u0026gt; Options for the request\n    - `timeout` \u0026lt;Number\u0026gt; timeout in ms\n    - `limit` \u0026lt;Number\u0026gt; maximum requests per available worker\n  - `callback` \u0026lt;Function\u0026gt;\n\nMaps a number of requests over the amount of registered workers / PeerRPCServers.\n\n[Example](https://github.com/bitfinexcom/grenache-nodejs-ws/tree/master/examples/rpc_cert_whitelist_server.js).\n\n\n#### peer.request(name, payload, [options], callback)\n  - `name` \u0026lt;String\u0026gt; Name of the service to address\n  - `payload` \u0026lt;String\u0026gt; Payload to send\n  - `options` \u0026lt;Object\u0026gt; Options for the request\n    - `timeout` \u0026lt;Number\u0026gt; timeout in ms\n    - `retry` \u0026lt;Number\u0026gt; attempts to make before giving up. default is 1\n  - `callback` \u0026lt;Function\u0026gt;\n\nSends a single request to a RPC server/worker.\n\n[Example](https://github.com/bitfinexcom/grenache-nodejs-ws/tree/master/examples/rpc_cert_whitelist_client.js).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitfinexcom%2Fgrenache-nodejs-ws-tls","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitfinexcom%2Fgrenache-nodejs-ws-tls","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitfinexcom%2Fgrenache-nodejs-ws-tls/lists"}