{"bugs":{"url":"https://github.com/hyperswarm/dht/issues"},"dist":{"shasum":"eb9f4c314715723ed7e7dcec2b3dbe2722fddda2","tarball":"https://registry.npmjs.org/@hyperswarm/dht/-/dht-5.0.25.tgz","fileCount":33,"integrity":"sha512-x8Fpvp96NSb3M/0Fap2rm70obpNd0fe8oJnwZxJfIvxQtItYFVCrD8URsI+0Fxt4tNINMxnE9h3MaKoaxePP2A==","signatures":[{"sig":"MEYCIQD4joMPFrHN1byhIuO7A2sWXG9WdG2V+IEQD+HKfIbmlwIhAPqCWENsU2Jo2AvJFEEBV2KLgLw6JB7yXccXTZBMwhL5","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":138701,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.10.10\r\nComment: https://openpgpjs.org\r\n\r\nwsFzBAEBCAAGBQJia7UzACEJED1NWxICdlZqFiEECWMYAoorWMhJKdjhPU1b\r\nEgJ2Vmo7fhAAk8Dz9mqRZa+HFzdUFlzJiemIVB9KuFmqbO8FWYfTFnRNuc4E\r\nYybKBwo+a453EnF2MSkT5bzqajla+dNTqNSjDvddTWtoJzMs6zTFZJ+EsRPd\r\nxcEk7yZG4YY6yC0B6Q5oiSFcM0de/vryJimY/Z/u5aA5DW9TDqw5v7Go05/y\r\nnhyMBMLaI7QyfXKqnzLvqG4SBRRT/DGz8Su+xbF1Y3TLsiITffQDLJl9xSFo\r\nIg94s/F8Nwf7pBUm1E8GRS7wfN4yxEpbX88xZWd0UuUIsq969lGBHqo/oRC/\r\nbK6MjigpT2e5lLM9Wii8mAs2XgWZpn+qaeDJ5kz5MrJOhTi7pgFWJyQLihm/\r\nEDpMgIDIg/hKAHR5lfI36lbTCG1cQlftQW6kRIDmTxYIPQcLwuoBD+yPw64Z\r\nNJvMj8O9RFoyl6S5jEfn1QlF0PqndSi+jaNvD2GCBuFEDGbMfJm7Int8+FUs\r\nFLg/MACt4imwSf2xEXiv9CUCLG5l3vDkN9ij+DpqdFN+p49oGkBel85rgl/S\r\nS1tUTGhyft5rSN29CGkfQULJO5l9Nx+UWFjL6TSFPTLcFZBd41qjqpoG1K14\r\n4WMPe6XOwqCVzpBwz4gPNWT3bIcKEEa8ElcLSjJIhFGNlXXlpQxQxKauB1OT\r\npi6kMimatoK0/hdfEJbnZpaPiS35roYClTQ=\r\n=k4r5\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":"180bcaf5612afa291dbd83327c583f0d97d5bb0c","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","debugging-stream":"^2.0.0","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.25_1651225907329_0.6380868787642107","host":"s3://npm-registry-packages"},"_id":"@hyperswarm/dht@5.0.25","version":"5.0.25"}