{"bugs":{"url":"https://github.com/hyperswarm/dht/issues"},"dist":{"shasum":"5747ada03ff161b15eaed4bd1338087806053f34","tarball":"https://registry.npmjs.org/@hyperswarm/dht/-/dht-5.0.17.tgz","fileCount":33,"integrity":"sha512-/ZlUSBTLR9uvzBF1V3sMzgzt8vtJp9FWikddPYYE0z0RXxpeyPkPlj+p6mLKKv66Obc4U/mYiuCc2f90vHVxcA==","signatures":[{"sig":"MEUCIQCLpBEjb7mcSWHquC6rNpO78J9eO/w3If4jzTtKojle9wIgM9p43/4e5Rl36/NTFWBgC4eef7kwDSiSCc5SoFUBsuc=","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":136701,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.10.10\r\nComment: https://openpgpjs.org\r\n\r\nwsFzBAEBCAAGBQJiITYWACEJED1NWxICdlZqFiEECWMYAoorWMhJKdjhPU1b\r\nEgJ2VmpJTw/8DPmPQwjNpU4bChaGiNwmCH+ZUzDVbbmwtVIiV6DtukuJ7Nui\r\nGefDJFd7/X2JPbmOOGRtIE2a0jSoaKwiVFFtinC11eyN+XQQtq55YLxkbCkP\r\na0u0ecAlLthSSCzfwztJOghkaA+xb6euJPj+k08DMdIpMdd0NKam8T68Ub45\r\n3ZC+f26SdjdHJyM0N8lvW4hqQzejADEOMSVL16b40CMG5VK5bO5hwy3w5mzm\r\nS8YVTZXKLeT+Yt64h1+5j+gZYxqmKavH4O1XoGoD7lOdHxuya/jdrsOc58sB\r\nPnqQr1iuo0GHgGgAiOFKyAnNYih4vywFOpZfXgvjzpfB2XUXcLbcl09sytcJ\r\n8ExhEU7c+/dFg5NZpSq4AnZyDYivzHIbtV/XI0yLqQHfSepnhegZGYwmhwg+\r\n642svvLFXOTbgObILs9vNS+Sl3j5iOgP+r1guhvH9X3XlS66jl+Sun6oo0po\r\nqlyPjmAVRRBePbhxbEdFfMrmNYIBJnp+7V9JxbLShAyFXJ7oyU1rZzeLnV5k\r\nFlN+i1OKVUwJSzstlDm4H5TFQdxqKddbyqaPWkE6cZxQT8N6UzgBfl+Xh1fI\r\noGnfmKTIgDQBgXqUXZ0N80RhvSJu4Y47pu8bYWsJqkIvK04K5FmFf35TQtPE\r\n4EflUL6lhSWH5JNKdo+SbGpurz9q+fHkLPk=\r\n=EHQW\r\n-----END PGP SIGNATURE-----\r\n"},"main":"index.js","name":"@hyperswarm/dht","author":{"url":"@mafintosh","name":"Mathias Buus"},"readme":"# @hyperswarm/dht\n\nThe DHT powering the HyperSwarm network\n\n```\nnpm install @hyperswarm/dht@next\n```\n\nBuilt on top of [dht-rpc](https://github.com/mafintosh/dht-rpc).\n\nThe Hyperswarm DHT uses a series of hole punching techniques to make sure connectivity works on most networks,\nand is mainly used to facilitate finding and connecting to peers using end to end encrypted Noise streams.\n\n## NOTE: v5\n\nNote that this is the README for v5 which is tagged under next.\nTo see the v4 documentation/code go to https://github.com/hyperswarm/dht/tree/v4\n\nAs v5 fully matures over the next month it will be shifted to npm latest.\n\n## Usage\n\nTo try it out, first instantiate a DHT instance\n\n``` js\nimport DHT from '@hyperswarm/dht'\n\nconst node = new DHT()\n```\n\nThen on one computer listen for connections\n\n``` js\n// create a server to listen for secure connections\nconst server = node.createServer()\n\nserver.on('connection', function (noiseSocket) {\n  // noiseSocket is E2E between you and the other peer\n  // pipe it somewhere like any duplex stream\n\n  console.log('Remote public key', noiseSocket.remotePublicKey)\n  console.log('Local public key', noiseSocket.publicKey) // same as keyPair.publicKey\n\n  process.stdin.pipe(noiseSocket).pipe(process.stdout)\n})\n\n// make a ed25519 keypair to listen on\nconst keyPair = DHT.keyPair()\n\n// this makes the server accept connections on this keypair\nawait server.listen(keyPair)\n```\n\nThen on another connect to the computer using the public key of the key-pair it is listening on\n\n``` js\n// publicKey here is keyPair.publicKey from above\nconst noiseSocket = anotherNode.connect(publicKey)\n\nnoiseSocket.on('open', function () {\n  // noiseSocket fully open with the other peer\n})\n\n// pipe it somewhere like any duplex stream\nprocess.stdin.pipe(noiseSocket).pipe(process.stdout)\n```\n\n## API\n\n#### `const node = new DHT([options])`\n\nCreate a new HyperSwarm DHT node.\n\nOptions include:\n\n```js\n{\n  // Optionally overwrite the default bootstrap servers\n  // Defaults to ['testnet1.hyperdht.org:49736', 'testnet2.hyperdht.org:49736', 'testnet3.hyperdht.org:49736']\n  bootstrap: ['host:port'],\n  keyPair // set the default key pair to use for server.listen and connect\n}\n```\n\nSee [dht-rpc](https://github.com/mafintosh/dht-rpc) for more options as HyperDHT inherits from that.\n\n*Note:* The default bootstrap servers are publicly served on behalf of the commons. To run a fully private DHT, start two or more dht nodes with an empty bootstrap array (`new DHT({bootstrap:[]})`) and then use the addresses of those nodes as the `bootstrap` option in all other dht nodes.\n\n#### `keyPair = DHT.keyPair([seed])`\n\nUse this method to generate the required keypair for DHT operations.\n\nReturns an object with `{publicKey, secretKey}`. `publicKey` holds a public key buffer, `secretKey` holds a private key buffer.\n\nIf you pass any options they are forwarded to dht-rpc.\n\n#### `await node.destroy([options])`\n\nFully destroy this DHT node.\n\nThis will also unannounce any running servers.\nIf you want to force close the node without waiting for the servers to unannounce pass `{ force: true }`.\n\n#### `node = DHT.bootstrapper(bind, [options])`\n\nIf you want to run your own Hyperswarm network use this method to easily create a bootstrap node.\n\n## Creating P2P servers\n\n#### `const server = node.createServer([options], [onconnection])`\n\nCreate a new server for accepting incoming encrypted P2P connections.\n\nOptions include:\n\n```js\n{\n  firewall (remotePublicKey, remoteHandshakePayload) {\n    // validate if you want a connection from remotePublicKey\n    // if you do return false, else return true\n    // remoteHandshakePayload contains their ip and some more info\n    return true\n  }\n}\n```\n\nYou can run servers on normal home computers, as the DHT will UDP holepunch connections for you.\n\n#### `await server.listen(keyPair)`\n\nMake the server listen on a keyPair.\nTo connect to this server use keyPair.publicKey as the connect address.\n\n#### `server.on('connection', encryptedConnection)`\n\nEmitted when a new encrypted connection has passed the firewall check.\n\n`encryptedConnection` is a [NoiseSecretStream](https://github.com/mafintosh/noise-secret-stream) instance.\n\nYou can check who you are connected to using `encryptedConnection.remotePublicKey` and `encryptedConnection.handshakeHash` contains a unique hash representing this crypto session (same on both sides).\n\n#### `server.on('listening')`\n\nEmitted when the server is fully listening on a keyPair.\n\n#### `server.address()`\n\nReturns an object containing the address of the server:\n\n```js\n{\n  host, // external IP of the server,\n  port, // external port of the server if predictable,\n  publicKey // public key of the server\n}\n```\n\nYou can also get this info from `node.remoteAddress()` minus the public key.\n\n#### `await server.close()`\n\nStop listening.\n\n#### `server.on('close')`\n\nEmitted when the server is fully closed.\n\n## Connecting to P2P servers\n\n#### `const encryptedConnection = node.connect(remotePublicKey, [options])`\n\nConnect to a remote server. Similar to `createServer` this performs UDP holepunching for P2P connectivity.\n\nOptions include:\n\n```js\n{\n  nodes: [...], // optional array of close dht nodes to speed up connecting\n  keyPair // optional key pair to use when connection (defaults to node.defaultKeyPair)\n}\n```\n\n#### `encryptedConnection.on('open')`\n\nEmitted when the encrypted connection has been fully established with the server.\n\n#### `encryptedConnection.remotePublicKey`\n\nThe public key of the remote peer.\n\n#### `encryptedConnection.publicKey`\n\nThe connections public key.\n\n## Additional peer discovery\n\n#### `const stream = node.lookup(topic, [options])`\n\nLook for peers in the DHT on the given topic. Topic should be a 32 byte buffer (normally a hash of something).\n\nThe returned stream looks like this\n\n```js\n{\n  // Who sent the response?\n  from: { id, host, port },\n  // What address they responded to (i.e. your address)\n  to: { host, port },\n  // List of peers announcing under this topic\n  peers: [ { publicKey, nodes: [{ host, port }, ...] } ]\n}\n```\n\nTo connect to the peers you should afterwards call `connect` with those public keys.\n\nIf you pass any options they are forwarded to dht-rpc.\n\n#### `const stream = node.announce(topic, keyPair, [relayAddresses], [options])`\n\nAnnounce that you are listening on a key-pair to the DHT under a specific topic.\n\nWhen announcing you'll send a signed proof to peers that you own the key-pair and wish to announce under the specific topic. Optionally you can provide up to 3 nodes, indicating which DHT nodes can relay messages to you - this speeds up connects later on for other users.\n\nAn announce does a parallel lookup so the stream returned looks like the lookup stream.\n\nCreating a server using `dht.createServer` automatically announces itself periodically on the key-pair it is listening on. When announcing the server under a specific topic, you can access the nodes it is close to using `server.nodes`.\n\nIf you pass any options they are forwarded to dht-rpc.\n\n#### `await node.unannounce(topic, keyPair, [options])`\n\nUnannounce a key-pair.\n\nIf you pass any options they are forwarded to dht-rpc.\n\n## Mutable/immutable records\n\n#### `{ hash, closestNodes } = await node.immutablePut(value, [options])`\n\nStore an immutable value in the DHT. When successful, the hash of the value is returned.\n\nIf you pass any options they are forwarded to dht-rpc.\n\n#### `{ value, from } = await node.immutableGet(hash, [options])`\n\nFetch an immutable value from the DHT. When successful, it returns the value corresponding to the hash.\n\nIf you pass any options they are forwarded to dht-rpc.\n\n#### `await { publicKey, closestNodes, seq, signature } = node.mutablePut(keyPair, value, [options])`\n\nStore a mutable value in the DHT.\n\nIf you pass any options they are forwarded to dht-rpc.\n\n#### `await { value, from, seq, signature } = node.mutableGet(publicKey, [options])`\n\nFetch a mutable value from the DHT.\n\nOptions:\n\n* `seq` - OPTIONAL, default `0`, a number which will only return values with corresponding `seq` values that are greater than or equal to the supplied `seq` option.\n* `latest` - OPTIONAL - default `false`, a boolean indicating whether the query should try to find the highest seq before returning, or just the first verified value larger than `options.seq` it sees.\n\nAny additional options you pass are forwarded to dht-rpc.\n\n## Additional API\n\nSee [dht-rpc](https://github.com/mafintosh/dht-rpc) for the additional APIs the DHT exposes.\n\n## CLI\n\nYou can start a DHT node in the command line, using the [@hyperswarm/cli](https://github.com/hyperswarm/cli) package:\n\n```sh\nnpm install -g @hyperswarm/cli\nhyperswarm-dht # runs a DHT node\n```\n\n## License\n\nMIT\n","browser":"browser.js","gitHead":"25f878ef5fd63f3446ae2b59b6c4cdad7a2ad9a1","license":"MIT","scripts":{"lint":"standard","test":"standard && brittle test/*.js"},"_npmUser":{"name":"mafintosh","email":"mathiasbuus@gmail.com"},"homepage":"https://github.com/hyperswarm/dht#readme","keywords":[],"standard":{"ignore":["**/*.mjs"]},"repository":{"url":"git+https://github.com/hyperswarm/dht.git","type":"git"},"_npmVersion":"6.14.16","description":"The DHT powering the HyperSwarm stack","directories":{"lib":"lib","test":"test"},"maintainers":[{"name":"kasperisager","email":"kasperisager@gmail.com"},{"name":"mafintosh","email":"mathiasbuus@gmail.com"},{"name":"pfrazee","email":"pfrazee@gmail.com"},{"name":"davidmarkclements","email":"david.mark.clements@gmail.com"}],"_nodeVersion":"16.13.2","dependencies":{"b4a":"^1.3.1","bogon":"^1.0.0","xache":"^1.0.0","dht-rpc":"^5.0.1","bind-easy":"^1.0.1","utp-native":"^2.5.3","record-cache":"^1.1.1","safety-catch":"^1.0.1","noise-curve-ed":"^1.0.2","noise-handshake":"^2.1.0","compact-encoding":"^2.4.1","sodium-universal":"^3.0.4","compact-encoding-net":"^1.0.1","@hyperswarm/secret-stream":"^5.1.0"},"_hasShrinkwrap":false,"readmeFilename":"README.md","devDependencies":{"brittle":"^2.0.0","standard":"^16.0.4"},"_npmOperationalInternal":{"tmp":"tmp/dht_5.0.17_1646343702444_0.7043091384769993","host":"s3://npm-registry-packages"},"_id":"@hyperswarm/dht@5.0.17","version":"5.0.17"}