swarmwire-cli 0.1.0 → 0.2.0

package/README.md

@@ -10,6 +10,12 @@ swarmwire send ./holiday-photos        # prints a link, keeps serving until you
 swarmwire get "<link>"                 # on the other machine: downloads it, resumable
 ```
 
+Generate QR codes for easy use with the [swarmwire android app](https://github.com/tibocub/swarmwire-mobile)
+```
+swarmwire send ./holiday-photos --qr   # also prints a QR code to flash from the android app
+swarmwire get --qr                     # displays a QR code that can be flashed to send a file from the android app
+```
+
 Anyone who knows what a file contains can find the people sharing it, whatever each calls it: two
 people sending the same file are one swarm. Pass `--private` to `send` for a link that carries a secret, so that only people
 holding the link can find you.
@@ -18,7 +24,7 @@ Both commands keep a two-line status current. Receiving looks like this:
 
 ```
 [=========>          ] 45% [2/3]  TOTAL: [154.2/344.0] MB
-UP: 1.1 MB/s   DOWN: 8.2 MB/s   Seeders: 1  Peers: 0
+UP: 1.1 MB/s  DOWN: 8.2 MB/s        Seeders: 1  Peers: 0
 ```
 
 When the download is done the bar is replaced by `[Done] you are now seeding.` and `get` keeps
@@ -35,10 +41,15 @@ are decimal: 1 MB is 1,000,000 bytes.
 
 | | |
 |---|---|
-| `send <path> [--private]` | share a file or folder; prints a link |
+| `send <path> [--private] [--qr]` | share a file or folder; prints a link (`--qr`: also draws it as a QR code) |
+| `get --qr [output] [--exit]` | draw a QR code and wait: a phone scans it and hands over a link (its own file, or one forwarded from another device) |
 | `get <link> [output] [--exit]` | fetch by link, then keep seeding it (`--exit`: leave instead); the output defaults to the name in the link |
 | `--bootstrap host:port` | use a private DHT instead of the public one (for tests) |
 
+`get --qr` listens on a fresh one-shot key on the DHT, shown in the QR code and printed below it as
+`swarmwire-recv://<key>`. It takes the first valid link anyone sends it, then downloads as usual.
+The QR codes go to stderr, so `send`'s stdout is still just the link.
+
 Needs Node 20 or later. Files are shared where they lie: nothing is copied or written next to them.
 
 ## Development

package/bin/swarmwire.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 /**
- * swarmwire send <path> [--private] [--bootstrap host:port]
+ * swarmwire send <path> [--private] [--qr] [--bootstrap host:port]
  * swarmwire get <link> [output] [--bootstrap host:port]
+ * swarmwire get --qr [output] [--bootstrap host:port]
  *
  * Deliberately two commands. Sending prints a link and keeps serving the file where it is;
  * getting takes that link and nothing else.
@@ -12,15 +13,19 @@ import { stat } from 'fs/promises'
 import Hyperswarm from 'hyperswarm'
 import DHT from 'hyperdht'
 import b4a from 'b4a'
+import { renderQr } from '../lib/qr.js'
+import { receive } from '../lib/rendezvous.js'
 import { Swarmwire, parseLink, groupLength, DEFAULT_GROUP_LOG } from 'swarmwire-lib'
 
 const USAGE = `swarmwire - content-addressed file transfer, peer to peer
 
   swarmwire send <path> [options]     share a file or folder; prints a link
   swarmwire get <link> [output]       fetch a file or folder by link
+  swarmwire get --qr [output]         show a QR code; a phone scans it and hands over a link
 
 Options:
   --private           only people holding the link can find you (default: anyone who knows the hash can)
+  --qr                send: also show the link as a QR code. get: wait for a link from a scanner
   --exit              get: leave when the download is done instead of seeding it
   --bootstrap <h:p>   use a private DHT instead of the public one
   --help
@@ -32,14 +37,14 @@ let shown = ''
 let drawn = false
 let lastPlain = ''
 
-const FLAGS = { private: false, exit: false, help: false, bootstrap: true } // true: takes a value
+const FLAGS = { private: false, exit: false, qr: false, help: false, bootstrap: true } // true: takes a value
 
 async function main () {
   const { command, args, flags } = parseArgs(process.argv.slice(2))
 
   if (flags.help || !command) return print(USAGE)
   if (command === 'send') return send(args[0], flags)
-  if (command === 'get') return get(args[0], args[1], flags)
+  if (command === 'get') return flags.qr ? get(null, args[0], flags) : get(args[0], args[1], flags)
 
   throw new Error(`unknown command: ${command}\n\n${USAGE}`)
 }
@@ -59,6 +64,7 @@ async function send (path, flags) {
     : await node.serve(path, { secret })
 
   print(link)
+  if (flags.qr) warn(renderQr(link, { color: process.stderr.isTTY }))
   warn(
     folder
       ? `serving ${path} (${files} files, ${bytes(size)})${flags.private ? ' privately' : ''}`
@@ -77,12 +83,18 @@ async function send (path, flags) {
 }
 
 async function get (link, output, flags) {
-  if (!link) throw new Error('get needs a link\n\n' + USAGE)
+  if (!link && !flags.qr) throw new Error('get needs a link\n\n' + USAGE)
+
+  const swarm = createSwarm(flags)
+
+  if (!link) {
+    link = await linkFromScanner(swarm)
+    if (!link) return swarm.destroy() // interrupted while waiting
+  }
 
   const parsed = parseLink(link)
   const out = output ?? safeName(parsed.name) ?? parsed.root.slice(0, 16)
 
-  const swarm = createSwarm(flags)
   const node = new Swarmwire({ swarm })
 
   warn(`fetching ${parsed.root.slice(0, 16)}... into ${out}`)
@@ -133,6 +145,19 @@ async function get (link, output, flags) {
   await swarm.destroy()
 }
 
+/** Show a QR code for a one-shot meeting point and wait for a scanner to hand us a link. */
+async function linkFromScanner (swarm) {
+  const meeting = await receive(swarm.dht)
+
+  warn(renderQr(meeting.url, { color: process.stderr.isTTY }))
+  warn(`${meeting.url}\nscan this with the swarmwire app and pick something to send; ctrl-c to cancel`)
+
+  const link = await Promise.race([meeting.link, interrupted().then(() => null)])
+  await meeting.close()
+
+  return link
+}
+
 /** Resolves on ctrl-c or a polite kill, so serving can end cleanly. */
 function interrupted () {
   return new Promise((resolve) => {

package/lib/qr.js

@@ -0,0 +1,25 @@
+import { encode } from 'uqr'
+
+const QUIET = 2 // modules of white around the code, as the spec asks
+
+/**
+ * A QR code as terminal text, two modules per character row. Black on white is set
+ * explicitly when `color` is true: on a dark theme the default colors would invert the code.
+ */
+export function renderQr (text, { color = true } = {}) {
+  const { data, size } = encode(text, { ecc: 'L', border: 0 })
+  const dark = (x, y) => x >= 0 && y >= 0 && x < size && y < size && data[y][x]
+
+  const rows = []
+  for (let y = -QUIET; y < size + QUIET; y += 2) {
+    let row = ''
+    for (let x = -QUIET; x < size + QUIET; x++) {
+      const top = dark(x, y)
+      const bottom = dark(x, y + 1)
+      row += top && bottom ? '█' : top ? '▀' : bottom ? '▄' : ' '
+    }
+    rows.push(color ? `\x1b[30;47m${row}\x1b[0m` : row)
+  }
+
+  return rows.join('\n')
+}

package/lib/rendezvous.js

@@ -0,0 +1,88 @@
+/**
+ * A one-shot meeting point for handing a link to a machine that cannot be reached by one.
+ *
+ * `receive` listens on a fresh DHT keypair and shows its public key (as a QR code); whoever
+ * scans it calls `deliver` with a link, the listener checks it is one and answers. No topic,
+ * no discovery: the key is the address, and it is good for exactly one link.
+ */
+
+import b4a from 'b4a'
+import { parseLink } from 'swarmwire-lib'
+
+export const SCHEME = 'swarmwire-recv://'
+const MAX_LINK = 4096 // a link is ~150 bytes; this only bounds what a stranger can make us buffer
+
+/**
+ * @param {import('hyperdht')} dht
+ * @returns {Promise<{url: string, link: Promise<string>, close: () => Promise<void>}>}
+ */
+export async function receive (dht) {
+  const keyPair = dht.constructor.keyPair()
+  let resolve
+  const link = new Promise((r) => { resolve = r })
+  let done = false
+
+  const server = dht.createServer((socket) => {
+    let buffer = ''
+    socket.setEncoding('utf8')
+    socket.on('error', () => {}) // a scanner that walks away is not our problem
+    socket.on('data', (chunk) => {
+      buffer += chunk
+      if (buffer.length > MAX_LINK) return socket.destroy()
+
+      const end = buffer.indexOf('\n')
+      if (end < 0) return
+
+      const candidate = buffer.slice(0, end).trim()
+      buffer = ''
+
+      try {
+        if (done) throw new Error('already received')
+        parseLink(candidate)
+      } catch {
+        return socket.end('invalid\n')
+      }
+
+      done = true
+      socket.end('ok\n')
+      resolve(candidate)
+    })
+  })
+
+  await server.listen(keyPair)
+
+  return {
+    url: SCHEME + b4a.toString(keyPair.publicKey, 'hex'),
+    link,
+    close: () => server.close()
+  }
+}
+
+/**
+ * Hand `link` to the listener at `url`. Resolves once it has accepted it.
+ *
+ * @param {import('hyperdht')} dht
+ * @param {string} url
+ * @param {string} link
+ */
+export async function deliver (dht, url, link) {
+  if (!url.startsWith(SCHEME)) throw new Error(`not a swarmwire receive address: ${url}`)
+  const publicKey = b4a.from(url.slice(SCHEME.length), 'hex')
+  if (publicKey.length !== 32) throw new Error(`not a swarmwire receive address: ${url}`)
+
+  const socket = dht.connect(publicKey)
+  socket.setEncoding('utf8')
+
+  const answer = new Promise((resolve, reject) => {
+    let reply = ''
+    socket.on('data', (chunk) => { reply += chunk })
+    socket.on('error', reject)
+    socket.on('end', () => { socket.end(); resolve(reply.trim()) }) // the listener half-closes after its answer
+    socket.on('close', () => resolve(reply.trim()))
+  })
+
+  socket.write(link + '\n')
+  const reply = await answer
+
+  if (reply !== 'ok') throw new Error(`receiver refused the link${reply ? `: ${reply}` : ''}`)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swarmwire-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Send a file or folder to someone with a link. Peer to peer, from the terminal.",
   "keywords": [
     "cli",
@@ -23,7 +23,8 @@
     "swarmwire": "bin/swarmwire.js"
   },
   "files": [
-    "bin/"
+    "bin/",
+    "lib/"
   ],
   "engines": {
     "node": ">=20"
@@ -35,7 +36,8 @@
     "b4a": "^1.9.0",
     "hyperdht": "^6.0.0",
     "hyperswarm": "^4.17.2",
-    "swarmwire-lib": "^0.4.0"
+    "swarmwire-lib": "^0.4.1",
+    "uqr": "^0.1.3"
   },
   "devDependencies": {
     "@hyperswarm/testnet": "^3.1.4",