BackTunnel/README.md

# BackTunnel – Secure Reverse SSH Folder Sharing Toolkit

**BackTunnel** is a lightweight toolkit to share and mount folders between Linux machines behind NAT or firewalls using **reverse SSH tunnels**.  
No third-party relay, no cloud dependency – just peer-to-peer, temporary, SSH-based access.

---

## ⚡ Quick Start

### 1. Accessor: Prepare your key (one-time)

```bash
backtunnel-keys print
```

Send the printed public key to the sharer.

### 2. Sharer: Start sharing and authorize the accessor

```bash
backtunnel-share ~/Documents with alice@remotehost for 2h -i --allow-key ./alice.pub
```

This injects a **temporary, restricted SFTP-only key** and prints an invite.

### 3. Accessor: Mount the shared folder

```bash
backtunnel-access '/home/sharer/Documents' from alice@remotehost -p 2222 -m ~/remote-rssh
```

Unmount with:

```bash
backtunnel-umount ~/remote-rssh
```

---

## ✨ Features

- **NAT/firewall friendly**: works without port forwarding.
- **Temporary by design**: shares auto-expire after a set duration.
- **Invite workflow**: sharer sends a one-liner or QR code to accessor.
- **Restricted keys**: accessor keys are usable only for SFTP via the reverse tunnel and can be auto-added for the session.
- **Profiles**: save defaults and common remotes in profiles.ini.
- **Host key policy**: configurable StrictHostKeyChecking via BACKTUNNEL_HOSTKEY_POLICY.
- **Desktop integration**: Dolphin (KDE) service menus for GUI/TUI sharing and access.
- **Convenient TUIs/GUI**: guided prompts for sharer/accessor; terminal opener detects installed terminals.
- **Bash completion**: contextual completion for both CLI commands and TUIs.
- **Logs with rotation**: servicemenu invocations write logs and keep the last 10 entries.

---

## 🧠 Roles and Flow

- Sharer: exposes a local SSH service back to a remote host for a limited time. Runs backtunnel-share.
- Accessor: connects to the sharer via the remote host’s `127.0.0.1:PORT` and mounts a folder with sshfs. Runs backtunnel-access.
- Reverse tunnel: the sharer’s ssh -R binds `127.0.0.1:PORT` on the remote host and forwards back to the sharer’s sshd.

---

## ✅ Requirements

- Linux with Bash
- OpenSSH client (ssh, sftp)
- sshfs (FUSE) on the accessor machine
- Optional:
  - qrencode (for QR code invites)
  - A terminal emulator for service menu helpers (e.g., konsole, gnome-terminal, wezterm, kitty, etc.)

---

## 🔑 Commands

### Sharer side

- backtunnel-share
  - Start a time-bounded reverse SSH tunnel and optionally print an invite.
  - Syntax:
    ```bash
    backtunnel-share /path/to/folder with user@host for <duration> [options]
    ```
  - Duration: 10m, 30m, 1h, 2h, 6h, 12h, 1d, 2d (single unit e.g., 30m, 2h, 1d)
  - Options:
    - -p, --tunnel-port N: Remote bind port (default: 2222)
    - -l, --local-ssh-port N: Local sshd port to forward to (default: 22)
    - -i, --invite: Print a one-liner invite for the accessor
    - --invite-mount PATH: Suggested mount point in the invite (default: $HOME/remote-rssh)
    - --invite-file FILE: Save the invite text (with unmount hint) to a file
    - --qr: Also show a QR code for the invite (requires qrencode)
    - --allow-key FILE: Temporarily authorize an accessor public key for this session
    - --allow-known NAME: Authorize a stored key (~/.config/backtunnel/authorized/NAME.pub)
    - -h, --help: Show usage

- backtunnel-share-tui
  - Minimal TUI wrapper prompting for remote, duration, ports, and invite options, then runs backtunnel-share.
  - Syntax:
    ```bash
    backtunnel-share-tui <folder>
    ```

- backtunnel-authorize
  - Store a named accessor public key for --allow-known usage.
  - Syntax:
    ```bash
    backtunnel-authorize <name> <pubkey-file>
    ```
  - Stores at: `${XDG_CONFIG_HOME:-$HOME/.config}/backtunnel/authorized/<name>.pub`

### Accessor side

- backtunnel-access
  - Mount a folder over SFTP via the reverse tunnel’s `127.0.0.1:PORT`.
  - Syntax:
    ```bash
    backtunnel-access /remote/folder from user@host [-p PORT] [-m MOUNTPOINT]
    ```
  - Options:
    - -p, --port N: Tunnel port on the remote host (default: 2222)
    - -m, --mount-point PATH: Local mount point (default: $HOME/remote-rssh)
    - -h, --help: Show usage
  - Behavior:
    - Checks mount point readiness and warns if not empty.
    - Tries passwordless auth via a dedicated identity if present (~/.ssh/id_ed25519_backtunnel).
    - Performs a quick SFTP visibility check of the target folder.
    - Mounts with reconnect/keepalives.

- backtunnel-access-tui
  - Minimal TUI wrapper prompting for remote, tunnel port, remote folder, and mount point.
  - Syntax:
    ```bash
    backtunnel-access-tui <selected-dir>
    ```

- backtunnel-keys
  - Manage the accessor-side dedicated key pair (~/.ssh/id_ed25519_backtunnel).
  - Syntax:
    ```bash
    backtunnel-keys print     # emit public key (generate if missing)
    backtunnel-keys path      # show key paths
    ```

- backtunnel-auth-setup
  - Initialize a tunnel-only, SFTP-only authorized_keys entry on the remote (via the tunnel).
  - Syntax:
    ```bash
    backtunnel-auth-setup [-p PORT] user@localhost
    ```
  - Installs a restricted entry:
    from="127.0.0.1",command="internal-sftp",restrict <pubkey>

- backtunnel-umount
  - Portable unmount helper (prefers fusermount3, then fusermount, then umount).
  - Syntax:

    ```bash
    backtunnel-umount <mountpoint>
    ```

- backtunnel-open-term
  - Launch a command in an available terminal emulator; logs output with simple rotation.
  - Automatically detects terminals (prefers konsole on KDE; supports wezterm, kitty, alacritty, gnome-terminal, kgx, tilix, xfce4-terminal, xterm).
  - Used by service menus/GUI wrappers.

---

## 🔒 Security Model

- Reverse tunnel bind: remote side binds on `127.0.0.1:PORT` (loopback only).
- Access is SFTP-based:
  - Invite flow can be paired with a restricted authorized_keys entry:
    - from="127.0.0.1",command="internal-sftp",restrict
  - This limits usage to SFTP over the reverse tunnel only; no shell or port forwarding.
- Temporary authorization:
  - Sharer can temporarily add an accessor public key for the session; it’s removed on exit.
- Host key policy:
  - Controlled via the environment variable BACKTUNNEL_HOSTKEY_POLICY with values:
    - accept-new (default), yes, no, ask
  - Applied to ssh, sftp, and the ssh command used by sshfs.

---

## 🧩 Profiles

- Config locations (higher precedence first):
  - `${XDG_CONFIG_HOME:-$HOME/.config}/backtunnel/profiles.ini`
  - /etc/backtunnel/profiles.ini
  - /usr/share/backtunnel/profiles.ini
- Example:

```ini
[default]
tunnel_port=2222
local_ssh_port=22
invite_mount=$HOME/remote-rssh
invite=true
qr=false

[work]
user=alice
host=vps.example.com
tunnel_port=4422
```
  
- Usage with @profile:
  ```bash
  backtunnel-share ~/reports with @work for 6h -i --allow-known alice
  ```

---

## 🧭 Bash Completion

- Source completions/backtunnel.bash or install it via your system’s completion.d directory.
- Provides:
  - Keyword scaffolding (with/from/for)
  - @profile expansion
  - Suggestions for durations and ports
  - Key name/file completion for --allow-known/--allow-key
  - Path completion for the first positional and mount path options
- Includes minimal completion for TUIs (first positional directory).

---

## 🖥️ Desktop Integration (KDE Dolphin)

- Right-click in a folder:
  - “Share via BackTunnel…” → opens a GUI/TUI flow for the sharer.
  - “Access via BackTunnel (mount here)…” → opens a GUI/TUI flow for the accessor.
- Logs:
  ```
  ~/.local/state/backtunnel/servicemenu.*.log
  ```
  The launcher keeps the last 10 logs (simple rotation).

---

## 🌐 Environment Variables

- BACKTUNNEL_HOSTKEY_POLICY
  - Controls StrictHostKeyChecking for ssh/sftp/sshfs:
  - Values: accept-new (default), yes, no, ask
  - Example:
    ```bash
    BACKTUNNEL_HOSTKEY_POLICY=strict   # alias for 'yes' in many contexts
    BACKTUNNEL_HOSTKEY_POLICY=accept-new
    ```

---

## 🛠️ Installation

### From source

```bash
sudo bash scripts/install.sh
make init   # copy example profiles.ini
```

### Arch Linux

```bash
makepkg -si
```

Uninstall:

```bash
sudo bash scripts/uninstall.sh
# or with purge of defaults
sudo PURGE=1 bash scripts/uninstall.sh
```

---

## 🔍 Troubleshooting

- Port already in use on remote:
  - backtunnel-share warns if `127.0.0.1:PORT` is busy; choose another with -p.
- Missing sshfs:
  - Install sshfs on the accessor machine; ensure FUSE is available.
- SFTP path is not listable:
  - backtunnel-access warns if SFTP cannot list the path. Verify folder existence and permissions.
- Passwordless auth isn't set:
  - Try:
    ```bash
    backtunnel-auth-setup -p <PORT> <user>@localhost
    ```
- Unmount fails:
  - Use the portable helper:
    ```bash
    backtunnel-umount <mountpoint>
    ```

---

## 🧪 Testing

- Bats scaffolds are provided to extend:
  - tests/test-umount.bats
  - tests/test-hostkey-policy.bats

Run tests (example):

```bash
bats tests
```

---

## 📖 Man Page

```bash 
man backtunnel
```

---

## 🧾 License
GNU GPL v3.0  
© 2025 LUXIM d.o.o., Slovenia – Matjaž Mozetič