# dsh-remote-gateway

[中文](../README.md) | **English**

Provides a secure reverse proxy for DeepSeek Harness.

DSH itself **always listens only on** `127.0.0.1`. The gateway securely proxies DSH to make it available on the local network.

## How It Works

```text
Browser
  → dsh-remote-gateway (allowlist + password authentication)
  → http://127.0.0.1:<DSH Web port>
```

## Requirements

- DSH `0.1.1-rc.2` or a newer compatible version
- Node.js `^22.23.2 || ^24.19.0` (use the latest security patch in a supported release line)
- pnpm

## Installation

Install from GitHub:

```sh
dsh plugin --profile web add github:RyensX/dsh-remote-gateway
```

Install from source:

```sh
pnpm install
pnpm build
dsh plugin --profile web add .
```

Uninstall:

```sh
dsh plugin --profile web remove dsh-remote-gateway
```

## Gateway Configuration

The settings page provides:

- A remote gateway switch, disabled by default, with changes taking effect immediately;
- Current access addresses, network interface names, and corresponding QR codes;
- A listen address, defaulting to `127.0.0.1`; explicitly select `0.0.0.0` or an interface address for LAN access;
- A port;
- An IP allowlist;
- Additional exact DNS Host names or NAT-facing IPs;
- A sliding authentication expiry, defaulting to 180 minutes;
- Password changes;
- Optional HTTPS certificate and private key settings.

All settings take effect live after **Save** is clicked; restarting DSH is not required.

Each token has an independent sliding expiry and a seven-day absolute lifetime; server pushes and heartbeats do not refresh it.

Before first use, set an access password locally.

When DSH is opened through an authenticated gateway address, the plugin installs a compatibility layer before the DSH client connection service is published. Native Models, Plugins, and other Settings pages therefore continue to use the Host Settings service instead of falling back to browser-memory settings.

## Remote Access

To support a variety of remote-access setups and improve data security, the plugin does not provide Internet access by itself. Use it together with Tailscale, ZeroTier, Cloudflare Tunnel, a company-managed VPN, or a similar solution.

After configuring one of these services, open the Gateway settings page to see the available access addresses.

> The gateway can also be exposed publicly, but this is not recommended. The tools above provide a safer and more controllable setup.

### Adding Workspaces and Opening Configuration Files Remotely

When a workspace is added through a gateway address, the plugin opens an in-browser picker for a folder on the host instead of showing an operating-system dialog on the computer running DSH that a remote user cannot operate.

Choosing **Open configuration file** in the upper-right corner of Settings opens the plugin's in-page YAML/JSON editor; local access continues to use DSH's original system text editor.

Both operations are protected by authentication.

### IP Allowlist

For better security, configure an allowlist when only specific devices need access.

Enter one item per line. Exact IPv4 addresses, IPv6 addresses, and CIDR ranges are supported. For example:

```text
192.168.1.20
192.168.1.0/24
fd00::/8
```

Leave the allowlist empty to permit connections from any source IP. The allowlist is an additional admission check; allowed clients must still enter the password. The source IP is read directly from the TCP socket, and forwarded proxy headers are not trusted.

### Access Host Names

The gateway always accepts local interface IP addresses and `localhost`. To use a LAN certificate name, custom DNS name, or container/NAT-facing IP, add each exact value to **Additional allowed Hosts**, for example `dsh.home.example`. Unlisted Host values receive `421` to prevent DNS rebinding. Enter an exact host name or IP without a scheme or port.

### HTTPS

HTTPS uses PEM files stored on the host machine:

```yaml
dsh-remote-gateway:
  tls:
    enabled: true
    certPath: /absolute/path/to/cert.pem
    keyPath: /absolute/path/to/key.pem
```

The certificate and private-key paths must be absolute regular files no larger than 1 MiB; devices, pipes, and directories are rejected. Saving certificate settings immediately loads the certificate and replaces the listener. If the certificate cannot be read or parsed, the gateway does not fall back to HTTP; the previous listener remains available and the local settings page displays the error. Overwriting certificate files at the same paths does not trigger a reload; changes to file contents alone still require restarting DSH.

HTTP mode is suitable only for temporary use on a trusted LAN. The authentication and settings pages display a plaintext-transmission warning; passwords, session cookies, and DSH content may be visible to an observer on the same network. For long-term use or any non-loopback listener, configure HTTPS together with an IP allowlist and host firewall rules.

## Development Checks

```sh
pnpm typecheck
pnpm lint
pnpm test
pnpm build
pnpm pack --dry-run
```