opencode-ssh-exec 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 opencode-ssh-exec contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# opencode-ssh-exec
+
+OpenCode plugin for system OpenSSH. It supports one-shot commands, bounded stdin, configurable deadlines, and retained SSH processes whose output can be polled while they run.
+
+## Requirements
+
+- OpenCode with `@opencode-ai/plugin` 1.15.12 or newer
+- Node.js 22 or newer
+- A system `ssh` client and non-interactive key or `ssh-agent` authentication
+
+## Install
+
+Add the package and tool permissions to `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-ssh-exec"],
+  "permission": {
+    "ssh_exec": "ask",
+    "ssh_start": "ask",
+    "ssh_process": "ask"
+  }
+}
+```
+
+Restart OpenCode after changing plugin configuration.
+
+Keep these permissions at `ask` globally. Set them to `deny` on read-only subagents. Environments that automatically approve `ask` prompts do not gain this confirmation boundary.
+
+Plugin options use OpenCode's tuple form:
+
+```json
+{
+  "plugin": [
+    [
+      "opencode-ssh-exec",
+      {
+        "defaultTimeoutSeconds": 300,
+        "maxTimeoutSeconds": 86400,
+        "hostKeyPolicy": "accept-new",
+        "updateHostKeys": true
+      }
+    ]
+  ]
+}
+```
+
+## Tools
+
+### `ssh_exec`
+
+Runs one command and returns after it exits. `stdinText` is optional, `timeoutSeconds` can be 1 to the configured maximum (24 hours by default), and `maxOutputBytes` can lower the configured ceiling for one call.
+
+### `ssh_start`
+
+Starts an SSH process and immediately returns a handle. This avoids waiting for a long build or log command to finish. `maxOutputBytes` controls its unpolled output buffer. A remote shell such as `sh` can retain cwd and environment state, but the caller is responsible for command framing and interpreting shell output.
+
+### `ssh_process`
+
+Manages a retained process:
+
+- `poll`: drain output accumulated since the previous poll
+- `status`: inspect state without draining output
+- `write`: send `stdinText` and optionally close stdin
+- `stop`: stop the local SSH process
+- `close`: release an exited handle
+
+OpenCode custom tools do not currently expose true output streaming. `ssh_start` plus repeated `ssh_process` polls is the supported progress mechanism.
+
+## Options
+
+| Option | Default | Notes |
+|---|---:|---|
+| `defaultTimeoutSeconds` | `60` | Default local SSH deadline |
+| `maxTimeoutSeconds` | `86400` | Hard per-call timeout ceiling |
+| `connectTimeoutSeconds` | `15` | OpenSSH connection timeout |
+| `maxOutputBytes` | `1048576` | Operator-enforced one-shot/output-buffer ceiling |
+| `maxInputBytes` | `262144` | Per-write UTF-8 stdin limit; hard maximum is 1 MiB |
+| `maxProcesses` | `8` | Retained handles per plugin instance |
+| `maxProcessesPerSession` | `4` | Retained handles owned by one OpenCode session |
+| `processRetentionSeconds` | `600` | Time to retain an exited handle |
+| `hostKeyPolicy` | `accept-new` | `accept-new` or `strict` |
+| `updateHostKeys` | `true` | Learn additional host keys after a trusted connection |
+| `connectionReuse` | `false` | POSIX only; enables OpenSSH ControlMaster |
+| `controlPersistSeconds` | `30` | ControlMaster idle lifetime |
+| `sshExecutable` | platform default | Trusted absolute system SSH executable path |
+
+## Security Model
+
+- `accept-new` is trust-on-first-use. It makes first connection easy but cannot detect an attacker present on that first connection. Changed host keys are still rejected. Use `hostKeyPolicy: "strict"` when fingerprints are provisioned separately.
+- `UpdateHostKeys=yes` can update the user's known-hosts file only after authentication with an already trusted key. It does not make a changed current key trusted.
+- Timeout, abort, and `ssh_process stop` terminate only the local SSH client. A remote process may continue. The plugin reports the remote outcome as unknown; do not automatically retry commands with side effects.
+- `stdinText` is recorded as an OpenCode tool argument. Do not use it for passwords, tokens, private keys, or other secrets.
+- SSH config is interpreted by OpenSSH instead of a partial custom parser. Treat `~/.ssh/config` as trusted local code: directives such as `Match exec`, `ProxyCommand`, `KnownHostsCommand`, and provider helpers can execute local programs.
+- Host input is restricted to a safe ASCII alias/hostname grammar to prevent unsafe expansion by SSH config helper commands. Configure usernames, ports, IPv6 addresses, and jump hosts in SSH config under a simple alias.
+- Agent, X11, port, and tunnel forwarding are disabled by generated command-line options. `BatchMode=yes` prevents password prompts.
+- Retained process handles are scoped to one OpenCode session, bounded, and removed after their retention period. Plugin disposal attempts to stop active local SSH processes.
+- Deleting an OpenCode session requests termination of that session's retained local SSH processes.
+- Connection reuse is disabled by default and rejected for native Windows OpenSSH. On POSIX it uses a private temporary `ControlPath` and a short `ControlPersist` lifetime. A control socket is an authenticated capability available to local processes running as the same user.
+- Remote stdout/stderr is untrusted and may contain prompt-injection text or secrets. Never treat it as instructions; filter or redact sensitive logs on the remote host before returning them to OpenCode.
+
+## License
+
+MIT

package/dist/server.d.ts

@@ -0,0 +1,38 @@
+import { type Plugin } from "@opencode-ai/plugin";
+type HostKeyPolicy = "strict" | "accept-new";
+export type SshPluginOptions = {
+    defaultTimeoutSeconds: number;
+    maxTimeoutSeconds: number;
+    connectTimeoutSeconds: number;
+    maxOutputBytes: number;
+    maxInputBytes: number;
+    maxProcesses: number;
+    maxProcessesPerSession: number;
+    processRetentionSeconds: number;
+    hostKeyPolicy: HostKeyPolicy;
+    updateHostKeys: boolean;
+    connectionReuse: boolean;
+    controlPersistSeconds: number;
+    sshExecutable: string;
+};
+type RuntimeOptions = SshPluginOptions & {
+    controlPath?: string;
+    usedControlHosts?: Set<string>;
+    executablePrefixArgs?: string[];
+};
+type SshCommandInput = {
+    host: string;
+    command: string;
+    remoteCwd?: string;
+    stdin: boolean;
+    timeoutSeconds: number;
+};
+export declare function parseOptions(raw: Record<string, unknown>): SshPluginOptions;
+export declare function buildSshArgs(input: SshCommandInput, options: RuntimeOptions): string[];
+export declare function createServerForTesting(executablePrefixArgs: string[]): Plugin;
+declare const pluginModule: {
+    id: string;
+    server: Plugin;
+};
+export default pluginModule;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAOA,OAAO,EAEL,KAAK,MAAM,EAIZ,MAAM,qBAAqB,CAAC;AAe7B,KAAK,aAAa,GAAG,QAAQ,GAAG,YAAY,CAAC;AAE7C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,uBAAuB,EAAE,MAAM,CAAC;IAChC,aAAa,EAAE,aAAa,CAAC;IAC7B,cAAc,EAAE,OAAO,CAAC;IACxB,eAAe,EAAE,OAAO,CAAC;IACzB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,KAAK,cAAc,GAAG,gBAAgB,GAAG;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC/B,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;CACjC,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAoGF,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,gBAAgB,CA0H3E;AAiCD,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,YA8B3E;AA6/BD,wBAAgB,sBAAsB,CAAC,oBAAoB,EAAE,MAAM,EAAE,UAEpE;AAID,QAAA,MAAM,YAAY;;;CAGM,CAAC;AAEzB,eAAe,YAAY,CAAC"}