dsh-vpn-ops

简体中文

Safety-gated WireGuard and VLESS Reality operations for DeepSeek Harness (DSH).

dsh-vpn-ops is a real DSH bundle: it ships cordis.patch.yml, exports a Cordis apply(ctx, config) lifecycle entry point, and registers eight typed tools. It turns a reviewed, allowlisted server definition into repeatable preflight, plan, apply, status, verification, rollback, and client-export operations.

Status: 0.1.0 initial public release. The bundle load path is verified against DSH 0.1.1-rc.2; production network rollout still requires an operator-owned staging server and acceptance test. See Compatibility and Limitations.

Why this is not “SSH from the model”

The model can choose only a configured targetId and clientId. It cannot supply a host, credential, remote path, package URL, or shell command.

• Strict host-key checking and public-key-only SSH are mandatory.
• Every process is spawned with an argv array; no local shell is used.
• Remote work runs a fixed helper shipped in the reviewed package.
• Remote mutation defaults to off.
• vpn_apply requires a fresh, persisted plan, an unchanged remote baseline, and the exact confirmation string returned by vpn_plan.
• Apply writes backups before the first managed-file change and automatically restores them if the transaction fails.
• Client secrets are never returned as tool values. Explicit export streams them into new local mode-0600 files and returns only paths, sizes, and SHA-256 evidence.
• The npm package has no preinstall, install, postinstall, prepare, or prepack lifecycle script.

Read the complete threat model before enabling changes.

Tools

Tool	Changes state	Gate
vpn_targets	No	None
vpn_preflight	No	Allowlisted target
vpn_status	No	Allowlisted target
vpn_plan	Local non-secret plan file	Preflight must pass
vpn_apply	Yes, remote	allowMutations, fresh plan, exact confirmation
vpn_verify	No	Allowlisted target
vpn_rollback	Yes, remote	allowMutations, backup id, exact confirmation
vpn_export_client	Yes, local secret files	allowSecretExport, exact confirmation

Target prerequisites

The first release intentionally does not install operating-system packages or download Xray. Supply-chain policy remains with the server operator.

The target must be Debian or Ubuntu with systemd and these commands already available:

base64 flock install ip iptables jq mktemp openssl sha256sum ss sysctl systemctl
uuidgen wg wg-quick xray

The configured xrayBinary may point to a non-PATH installation. The SSH user must be root, or sudo: true must provide non-interactive root authority. Treat either credential as root-equivalent and keep it dedicated.

Before deployment, verify that:

1. UDP wireguardListenPort and TCP vlessPort are allowed by the provider and host firewalls.
2. publicInterface is the actual egress interface.
3. The REALITY realityDestination and realityServerName are suitable and under an acceptable abuse policy. Unauthenticated REALITY traffic is forwarded to the target; see the Xray documentation warning.
4. Xray accepts network: "raw", the target REALITY field, and xtls-rprx-vision in a dry-run configuration test.
5. The operator has an independent recovery channel such as a cloud serial console.

Install

GitHub release

Install a tagged release into an existing DSH profile:

dsh plugin --profile my-profile add github:zootguru/dsh-vpn-ops#v0.1.0

The repository commits built lib/ artifacts, so a Git install does not run a build lifecycle hook.

Local, reproducible tarball

pnpm install --frozen-lockfile
pnpm verify
pnpm pack --pack-destination ./artifacts
dsh plugin --profile my-profile add ./artifacts/dsh-vpn-ops-0.1.0.tgz

Configure

The bundle installs a disabled vpn-ops row. Override that row in the profile's user cordis.patch.yml:

- id: vpn-ops
  config:
    # Keep false until a reviewed vpn_plan is ready to execute.
    allowMutations: false
    # Enable only for an operator-approved client export session.
    allowSecretExport: false
    stateDirectory: /Users/operator/.local/state/dsh-vpn-ops
    connectTimeoutSeconds: 10
    commandTimeoutMs: 120000
    maxOutputBytes: 65536
    planTtlSeconds: 900
    targets:
      - id: la-edge
        host: vpn.example.net
        user: root
        sshPort: 22
        identityFile: /Users/operator/.ssh/dsh-vpn-ops_ed25519
        knownHostsFile: /Users/operator/.ssh/dsh-vpn-ops_known_hosts
        sudo: false
        publicEndpoint: vpn.example.net
        publicInterface: eth0
        remoteStateDirectory: /var/lib/dsh-vpn-ops

        wireguardInterface: wg0
        wireguardAddress: 10.66.66.1/24
        wireguardListenPort: 51820
        wireguardConfigPath: /etc/wireguard/wg0.conf
        wireguardService: wg-quick@wg0
        clientDns: 1.1.1.1
        clientMtu: 1420

        vlessListenAddress: 0.0.0.0
        vlessPort: 443
        realityServerName: www.example.com
        realityDestination: www.example.com:443
        xrayBinary: /usr/local/bin/xray
        xrayConfigPath: /usr/local/etc/xray/config.json
        xrayService: xray
        sysctlConfigPath: /etc/sysctl.d/99-dsh-vpn-ops.conf

        clients:
          - id: laptop
            wireguardAddress: 10.66.66.2/32
          - id: phone
            wireguardAddress: 10.66.66.3/32

identityFile must be a regular file inaccessible to group and others. knownHostsFile must be non-empty. Obtain the host key through the provider or another authenticated channel; do not trust an unverified ssh-keyscan result.

No example contains a real server address, UUID, private key, or client config.

Operate

Use this order:

1. vpn_targets
2. vpn_preflight({ targetId: "la-edge" })
3. vpn_status({ targetId: "la-edge" })
4. vpn_plan({ targetId: "la-edge" })
5. Review every change, the baseline deployment id, and the managed-state fingerprint. Any managed-file or service-state drift invalidates the plan.
6. Set allowMutations: true, let DSH reload the plugin, and call vpn_apply with the exact plan id and confirmation returned in step 4.
7. Read the returned backup id and verification result. A missing first handshake is informational; invalid configuration, inactive services, or closed listeners makes verification fail.
8. Set allowMutations: false again.

To export a configured client, temporarily enable allowSecretExport, obtain explicit operator approval for EXPORT <targetId> <clientId>, call vpn_export_client, move the generated files into an approved secret channel, then disable export and remove the local copies when no longer needed.

Rollback requires the exact backupId and confirmation ROLLBACK <targetId> <backupId>.

What apply manages

• WireGuard server and per-client X25519 keys.
• VLESS UUIDs and REALITY key material.
• WireGuard server configuration and client profiles.
• Xray VLESS + REALITY inbound configuration.
• IPv4 forwarding sysctl configuration.
• Service enable/restart for the configured WireGuard and Xray units.
• Per-apply backups and a current deployment marker under remoteStateDirectory.

Keys are generated on the target and remain under remoteStateDirectory/secrets with restrictive permissions. Existing managed keys are reused so repeated applies do not silently invalidate clients.

Compatibility

Component	Verified contract
DeepSeek Harness	0.1.1-rc.2
@deepseek-ai/dsh-tools	0.1.1-rc.2 exact peer
@deepseek-ai/cordis	4.0.1 exact peer
Node.js	^22.19.0 or >=24.0.0
Remote OS	Debian / Ubuntu with systemd
Xray configuration	Current target, password, and raw terminology; runtime preflight and dry-run required

DSH is a developer preview and may make breaking changes. Compatibility is an evidence statement, not a broad semver promise. The exact clean-profile procedure and results live in Verification.

Limitations

• No package installation, firewall-provider API, DNS update, cloud console, or certificate management.
• IPv4 WireGuard topology only; no IPv6 forwarding.
• Full-tunnel clients only (AllowedIPs = 0.0.0.0/0).
• One WireGuard interface and one VLESS Reality inbound per target.
• Service health and local listeners are verified; an end-to-end test from an independent external network remains the operator's responsibility.
• Client export writes secret material to the DSH host. The plugin does not send it to email, chat, cloud storage, or the model.
• Rollback covers managed configuration, client artifacts, sysctl, and prior service activity. It cannot reverse external firewall, provider, DNS, or routing changes because it never performs them.

Uninstall

Disable mutations, remove the bundle, and inspect the target manually before deleting remote state:

dsh plugin --profile my-profile remove dsh-vpn-ops

Uninstall intentionally does not delete remote configuration, keys, backups, or client files.

Development and evidence

pnpm install --frozen-lockfile
pnpm test:coverage
pnpm verify

The repository publishes:

• a lockfile and exact DSH compatibility peers;
• TypeScript declarations and built ESM;
• unit, failure-path, static security, transport, plan, and tool-surface tests;
• package and shell syntax gates;
• a CI matrix for supported Node lines;
• security policy, threat model, verification evidence, and release checklist.

License

MIT