feat(core): add SSH data access proxy CLI and core managers

2026-05-30 10:02:08 +00:00
commit 47d9846c93
23 changed files with 10399 additions and 0 deletions
@@ -0,0 +1,326 @@
+# dap
+
+`dap` is a data access proxy for SSH-based machines. It scans your OpenSSH config, lists configured hosts, adds and edits SSH host blocks, connects to remote machines, proxies remote ports, and mounts remote folders into your local filesystem.
+
+`dap` uses OpenSSH as the source of truth. Your `~/.ssh/config`, SSH agent, keys, `ProxyJump`, known hosts, and normal `ssh` behavior remain in control.
+
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
+## Install
+
+Install globally:
+
+```bash
+pnpm install -g dap
+```
+
+Or install in a project:
+
+```bash
+pnpm install dap
+```
+
+## Quick Start
+
+Open the interactive dashboard:
+
+```bash
+dap
+```
+
+List configured SSH hosts:
+
+```bash
+dap list
+```
+
+Add a host:
+
+```bash
+dap add production --hostname 203.0.113.10 --user root --identity-file ~/.ssh/id_ed25519
+```
+
+Connect to a host:
+
+```bash
+dap ssh production
+```
+
+Proxy a remote PostgreSQL port to your local machine:
+
+```bash
+dap proxy production --local 5433:127.0.0.1:5432
+```
+
+Mount a remote folder locally:
+
+```bash
+dap mount production:/var/www ./mounts/production-www
+```
+
+Check local system support:
+
+```bash
+dap doctor
+```
+
+## Commands
+
+### `dap`
+
+Starts the interactive dashboard.
+
+```bash
+dap
+```
+
+The dashboard can list hosts, add hosts, edit hosts, connect over SSH, start port proxies, mount remote paths, and run diagnostics.
+
+### `dap list`
+
+Lists hosts found in your SSH config.
+
+```bash
+dap list
+```
+
+`dap` reads the main config and included files.
+
+### `dap add`
+
+Adds a DAP-managed host block to the main SSH config.
+
+```bash
+dap add staging --hostname staging.example.com --user deploy --port 22 --identity-file ~/.ssh/id_ed25519
+```
+
+Generated block:
+
+```sshconfig
+# dap:begin staging
+Host staging
+  HostName staging.example.com
+  User deploy
+  Port 22
+  IdentityFile ~/.ssh/id_ed25519
+# dap:end staging
+```
+
+If required fields are missing, `dap add` asks for them interactively.
+
+### `dap edit <host>`
+
+Edits a host in the main SSH config.
+
+```bash
+dap edit production --user deploy --identity-file ~/.ssh/id_ed25519
+```
+
+Editable fields include:
+
+- `HostName`
+- `User`
+- `Port`
+- `IdentityFile`
+- `ProxyJump`
+- `LocalForward`
+- `RemoteForward`
+
+DAP-managed blocks are updated directly. Existing non-DAP host blocks are shown as a diff before writing unless `--yes` is passed.
+
+### `dap ssh <host>`
+
+Connects to a host using the system `ssh` binary.
+
+```bash
+dap ssh production
+```
+
+By default this starts a session bridge and temporarily places a `dap` command into the remote session `PATH`. The command is created in a temporary remote directory and removed when the SSH session exits.
+
+Disable the bridge when you want a plain SSH call:
+
+```bash
+dap ssh production --no-bridge
+```
+
+Pass raw SSH arguments after `--`:
+
+```bash
+dap ssh production -- -A
+```
+
+### Remote Session `dap`
+
+When you connect with `dap ssh <host>`, the remote shell receives a temporary `dap` command.
+
+Inside the remote session:
+
+```bash
+dap info
+```
+
+Mount the current remote directory into a local path:
+
+```bash
+dap mount . ./dap-mounts/project
+```
+
+The remote command talks back to the local DAP session through an SSH reverse forward. The bridge uses a one-time token and only exposes explicit DAP actions.
+
+The remote machine needs `curl` for bridged remote commands.
+
+### `dap proxy <host>`
+
+Starts an SSH local forward.
+
+```bash
+dap proxy production --local 5433:127.0.0.1:5432
+```
+
+This maps:
+
+```text
+localhost:5433 -> production:127.0.0.1:5432
+```
+
+Internally this uses:
+
+```bash
+ssh -N -L 5433:127.0.0.1:5432 production
+```
+
+### `dap mount <host>:<remotePath> <localPath>`
+
+Mounts a remote path into your local filesystem.
+
+```bash
+dap mount production:/srv/project ./mounts/project
+```
+
+Backends:
+
+- `sshfs`, preferred when available.
+- `rclone mount`, used as a fallback with the documented `--sftp-ssh` option so OpenSSH host aliases can still be used.
+
+Force a backend:
+
+```bash
+dap mount production:/srv/project ./mounts/project --backend sshfs
+```
+
+Linux requires FUSE. macOS requires macFUSE.
+
+### `dap unmount <localPath>`
+
+Unmounts a local mount path.
+
+```bash
+dap unmount ./mounts/project
+```
+
+On Linux, `dap` uses `fusermount3`, `fusermount`, or `umount`. On macOS, it uses `umount`.
+
+### `dap doctor`
+
+Checks the local system for required tools and platform support.
+
+```bash
+dap doctor
+```
+
+It checks:
+
+- `ssh`
+- `sshfs`
+- `rclone`
+- `~/.ssh/config`
+- FUSE on Linux
+- macFUSE on macOS
+
+## SSH Config Handling
+
+`dap` uses the main SSH config:
+
+```text
+~/.ssh/config
+```
+
+It also scans files referenced by `Include` directives.
+
+When adding new hosts, `dap` writes managed blocks directly to the main config. Managed blocks are wrapped with markers:
+
+```sshconfig
+# dap:begin production
+Host production
+  HostName 203.0.113.10
+  User root
+  IdentityFile ~/.ssh/id_ed25519
+# dap:end production
+```
+
+Before changing the main config, `dap` creates a timestamped backup:
+
+```text
+~/.ssh/config.dap-backup-2026-05-30T12-30-00-000Z
+```
+
+For existing non-DAP host blocks, `dap edit` shows a diff before writing.
+
+## Mounting Notes
+
+`sshfs` is the simplest backend because it maps directly to OpenSSH host aliases:
+
+```bash
+sshfs production:/srv/project ./mounts/project
+```
+
+`rclone mount` is available as a fallback. DAP invokes it with the external SSH option so your SSH config alias remains the connection entry point:
+
+```bash
+rclone mount :sftp:/srv/project ./mounts/project --sftp-ssh "ssh production" --sftp-shell-type none
+```
+
+## Safety Model
+
+`dap` follows these rules:
+
+- OpenSSH remains authoritative.
+- The main SSH config is backed up before writes.
+- DAP-created blocks are clearly marked.
+- Non-DAP host edits require diff confirmation by default.
+- Remote `dap` exists only for the current `dap ssh` session.
+- The remote session bridge uses a one-time token.
+- The bridge exposes explicit DAP actions, not arbitrary local shell execution.
+
+## Platform Support
+
+`dap` targets:
+
+- Linux
+- macOS
+
+Windows is not part of the initial scope.
+
+## License and Legal Information
+
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository [license.md](./license.md) file.
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
+
+### Company Information
+
+Task Venture Capital GmbH<br>
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.