Add invite and QR code features to backtunnel-share

2025-09-14 12:54:06 +02:00
parent d510d777ca
commit 07dbd79aa2
3 changed files with 134 additions and 4 deletions
--- a/README.md
+++ b/README.md
@@ -17,6 +17,32 @@ backtunnel-share /path/to/folder with remoteuser:remotehost for <duration> [opti
 **Options**
 - `-p, --tunnel-port <PORT>`: Remote port to expose with `-R` (default: 2222)
 - `-l, --local-ssh-port <PORT>`: Local sshd port to forward to (default: 22)
+- `-i, --invite`: Print a ready-to-copy access command for the remote user
+- `--invite-mount <PATH>`: Suggest mount point in the invite (default: `/mnt/remote-rssh`)
+- `--invite-file <FILE>`: Also write the invite text (including unmount hint) to a file
+- `--qr`: Render the invite as a QR code (requires `qrencode`)
+
+**Examples**
+```bash
+# Share for 2h
+backtunnel-share ~/projects with alice@vps.example.com for 2h
+
+# Share and print a one-liner invite for chat
+backtunnel-share ~/projects with alice@vps.example.com for 2h -i
+
+# Share with custom ports and QR invite
+backtunnel-share ~/projects with alice@vps.example.com for 1d -p 4422 -l 2222 -i --qr
+```
+
+The invite will look like this and can be pasted on the remote host:
+```bash
+backtunnel-access '/home/user/projects' from alice@vps.example.com -p 4422 -m '/mnt/remote-rssh'
+```
+
+Unmount on the remote side with:
+```bash
+fusermount -u /mnt/remote-rssh
+```

 ### `backtunnel-access`
 Mount a folder from the *remote* side via SSHFS.
@@ -30,6 +56,8 @@ backtunnel-access /path/to/folder from remoteuser:remotehost [options]
 - `-p, --port <PORT>`: Port on the remote host where the reverse tunnel listens (default: 2222)
 - `-m, --mount-point <PATH>`: Local mount point (default: `/mnt/remote-rssh`)

+---
+
 ## 🧰 Dolphin Service Menus

 Two context actions for Dolphin:
@@ -40,9 +68,15 @@ Installed into:
 - Plasma 6: `/usr/share/kio/servicemenus/`
 - Plasma 5: `/usr/share/kservices5/ServiceMenus/`

+---
+
 ## 🔐 Requirements
 - `ssh`, `sshfs`, `timeout`, `konsole`, `kdialog`
- Optional: `bash-completion`
+- Optional: 
+  - `bash-completion`
+  - `qrencode` (for QR-code invites)
+
+---

 ## 📦 Install
 ```bash
@@ -53,10 +87,14 @@ Uninstall:
 sudo bash scripts/uninstall.sh
 ```

+---
+
 ## 📖 Man Page
 ```bash
 man backtunnel
 ```

+---
+
 ## 🧾 License
 Licensed under **GNU GPL v3.0**. See `LICENSE`.
--- a/man/backtunnel.1
+++ b/man/backtunnel.1
@@ -1,4 +1,4 @@
-.TH backtunnel 1 "September 2025" "1.1" "BackTunnel – Reverse SSH Sharing Toolkit"
+.TH backtunnel 1 "September 2025" "1.2" "BackTunnel – Reverse SSH Sharing Toolkit"

 .SH NAME
 backtunnel-share, backtunnel-access \- Secure reverse SSH folder sharing and access
@@ -15,6 +15,9 @@ backtunnel-share, backtunnel-access \- Secure reverse SSH folder sharing and acc
 The tunnel exposes the local sshd (typically port 22) on a loopback port on the remote host using \fBssh -R\fR.
 The sharing ends automatically after the given \fIduration\fR via \fBtimeout\fR.

+With the \fB--invite\fR option, \fBbacktunnel-share\fR prints a ready-to-copy access command for the remote user,
+which can be pasted directly into a chat or terminal. The invite can also be rendered as a QR code or written to a file.
+
 \fBbacktunnel-access\fR mounts the shared folder from the remote side using \fBsshfs\fR by connecting to \fBlocalhost:<port>\fR on the remote host (the port exposed by \fBbacktunnel-share\fR).

 .SH OPTIONS
@@ -27,6 +30,22 @@ Remote port to bind with \fB-R\fR (default: 2222).
 .B -l, --local-ssh-port <PORT>
 Local sshd port to forward to (default: 22).

+.TP
+.B -i, --invite
+Print a ready-to-copy invite command for the remote user.
+
+.TP
+.B --invite-mount <PATH>
+Mount point suggested in the invite (default: /mnt/remote-rssh).
+
+.TP
+.B --invite-file <FILE>
+Also write the invite text (including unmount hint) to the given file.
+
+.TP
+.B --qr
+Render the invite as a terminal QR code (requires \fBqrencode\fR).
+
 .SS backtunnel-access options
 .TP
 .B -p, --port <PORT>
@@ -60,6 +79,16 @@ Share for 1 day, using custom ports:
 .B backtunnel-share
 /home/user/docs with alice:vps.example.com for 1d -p 4422 -l 2222

+.TP
+Share with invite printed:
+.B backtunnel-share
+/home/user/docs with alice@vps.example.com for 2h -i
+
+.TP
+Share with QR invite:
+.B backtunnel-share
+/home/user/docs with alice@vps.example.com for 2h -i --qr
+
 .TP
 Mount with default port and mount point:
 .B backtunnel-access
@@ -74,8 +103,11 @@ Mount with custom port and mount point:
 By default, \fBssh -R\fR binds to 127.0.0.1 on the remote side, limiting access to local users on the remote machine.
 The client connects to \fBlocalhost:<port>\fR from the remote host.

+The invite feature is intended for convenience: copy-paste the printed command into chat for the remote user.
+Unmount with \fBfusermount -u <mountpoint>\fR after use.
+
 .SH SEE ALSO
-ssh(1), sshfs(1), timeout(1), autossh(1), fusermount(1)
+ssh(1), sshfs(1), timeout(1), autossh(1), qrencode(1), fusermount(1)

 .SH AUTHOR
 Matjaž Mozetič
--- a/scripts/backtunnel-share
+++ b/scripts/backtunnel-share
@@ -4,7 +4,7 @@

 # backtunnel-share: Share a folder using reverse SSH for a limited duration
 # Syntax: backtunnel-share /path/to/folder with remoteuser:remotehost for 2h
-# Options: -p|--tunnel-port <PORT>  -l|--local-ssh-port <PORT>  -h|--help
+# Options: -p|--tunnel-port <PORT>  -l|--local-ssh-port <PORT>  -i|--invite [--invite-mount <PATH>] [--invite-file <FILE>] [--qr]  -h|--help

 set -euo pipefail

@@ -12,6 +12,11 @@ TUNNEL_PORT=2222       # remote-side port exposed via -R
 LOCAL_SSH_PORT=22      # local sshd port to forward to
 DURATION=""            # required: e.g. 30m, 2h, 1d

+INVITE=false           # print a ready-to-copy access command
+INVITE_MOUNT="/mnt/remote-rssh"
+INVITE_FILE=""
+QR=false               # render invite as terminal QR (requires qrencode)
+
 usage() {
  cat >&2 <<EOF
 Usage:
@@ -27,11 +32,16 @@ Positional (required, in order):
 Options:
  -p, --tunnel-port N       Remote tunnel port (default: ${TUNNEL_PORT})
  -l, --local-ssh-port N    Local sshd port to expose (default: ${LOCAL_SSH_PORT})
+  -i, --invite              Print a ready-to-copy access command for the remote side
+      --invite-mount PATH   Mount point suggested in invite (default: ${INVITE_MOUNT})
+      --invite-file FILE    Also write the invite text (with unmount hint) to FILE
+      --qr                  Also print a QR code (requires 'qrencode')
  -h, --help                Show this help

 Examples:
  $(basename "$0") ~/projects with alice:vps.example.com for 2h
  $(basename "$0") ~/projects with alice@vps.example.com for 1d -p 4422 -l 2222
+  $(basename "$0") ~/projects with alice@vps.example.com for 2h -i --qr
 EOF
  exit 1
 }
@@ -62,6 +72,24 @@ while [[ $# -gt 0 ]]; do
      LOCAL_SSH_PORT=$2
      shift 2
      ;;
+    -i|--invite)
+      INVITE=true
+      shift
+      ;;
+    --invite-mount)
+      [[ $# -lt 2 ]] && usage
+      INVITE_MOUNT=$2
+      shift 2
+      ;;
+    --invite-file)
+      [[ $# -lt 2 ]] && usage
+      INVITE_FILE=$2
+      shift 2
+      ;;
+    --qr)
+      QR=true
+      shift
+      ;;
    -h|--help)
      usage
      ;;
@@ -101,6 +129,38 @@ echo "    remote bind port    : ${TUNNEL_PORT} (on ${REMOTE_HOST})"
 echo "    remote user         : ${REMOTE_USER}"
 echo "    duration            : ${DURATION}"
 echo
+
+# --- print invite (optional) ---
+if $INVITE; then
+  INVITE_CMD="backtunnel-access '${FOLDER}' from ${REMOTE_USER}@${REMOTE_HOST} -p ${TUNNEL_PORT} -m '${INVITE_MOUNT}'"
+  INVITE_TEXT=$(
+    cat <<EOT
+# Paste this on the REMOTE host (or SSH there first, then paste):
+${INVITE_CMD}
+# Unmount when done:
+fusermount -u '${INVITE_MOUNT}'
+EOT
+  )
+  echo "🔗 Invite (copy to chat):"
+  echo "------------------------------------------------------------"
+  echo "${INVITE_CMD}"
+  echo "------------------------------------------------------------"
+  if [[ -n "${INVITE_FILE}" ]]; then
+    printf "%s\n" "${INVITE_TEXT}" > "${INVITE_FILE}"
+    echo "Saved invite to: ${INVITE_FILE}"
+  fi
+  if $QR; then
+    if command -v qrencode >/dev/null 2>&1; then
+      echo
+      echo "📱 QR (scan to copy the command):"
+      printf "%s" "${INVITE_CMD}" | qrencode -t ansiutf8
+    else
+      echo "⚠️  'qrencode' not installed; skipping QR."
+    fi
+  fi
+  echo
+fi
+
 echo "Tip: On the remote side, mount with:"
 echo "     backtunnel-access '${FOLDER}' from ${REMOTE_USER}@${REMOTE_HOST} -p ${TUNNEL_PORT}"