@godspeedai/cognate-execution-ssh 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# @godspeedai/cognate-execution-ssh — an SSH host as an execution world
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`sshExecutionWorld(options)` is an `ExecutionWorldProvider`: files over SFTP, commands over `exec`,
+behind the same `filesystem.*` / `process.exec` contracts as every other world. Nothing above the
+provider knows it is SSH.
+
+```ts
+const world = sshExecutionWorld({
+  worldId: "build-box", host: "build.example.com", username: "dev",
+  auth: { kind: "key", privateKeyPath: "~/.ssh/id_ed25519" },     // or { kind: "agent" } / { kind: "password", password }
+  hostKeys: { fingerprints: ["SHA256:…"] },                       // or { knownHostsPath } — REQUIRED
+  jump: [{ host: "bastion", username: "dev", auth: { kind: "agent" }, hostKeys: { knownHostsPath } }], // ProxyJump
+});
+```
+
+## What it guarantees
+
+| Guarantee | How |
+| --- | --- |
+| The server is who you pinned | A host-key policy is mandatory; no TOFU, no accept-anything mode. Mismatch → `HostKeyMismatchError`, never retried, raised before any authentication. Hashed/plain `known_hosts`, `[host]:port`, wildcards, negation and `@revoked` are honoured. |
+| Trust is a human act | `probeHostKey()` reads the key and *refuses* it, so nothing is authenticated or sent; show the fingerprint to a person, then pin it. |
+| Fail closed | An unreachable host, changed key or disposed world raises `WorldUnavailableError`. Nothing ever falls back to local execution. |
+| Containment | `resolve` rejects lexical escapes; a symlink inside the root pointing outside is refused before read/write/stat/list (SFTP `realpath`). |
+| A cancelled command really ends | Commands run under a supervisor: own process group, ended on `TERM` **or** when stdin reaches EOF (closed channel, dropped connection) — so it works against servers that ignore signal requests, and the whole process *tree* dies. |
+| Reconnect | A dropped connection is re-dialled on the next operation; idempotent file operations retry once, commands and writes never do. |
+| Disposal | `dispose()` closes live channels, SFTP and every hop; idempotent; later calls fail closed. |
+| No secrets leak | `metadata` carries host, port, user, auth *kind* and the verified host-key fingerprint — never a password, passphrase or key. |
+
+## Testing
+
+- `test/ssh.test.ts` runs the shared conformance suite and every behaviour above against a real
+  ssh2 `Server` (`./fixture`: auth, `exec` on a real shell, an SFTP subset, direct-tcpip forwarding).
+- The live gate (`just remote-workspaces-live`) runs the same suite against a **real OpenSSH sshd**
+  built in user space (`just setup-openssh`), and optionally against your own host
+  (`COGNATE_SSH_HOST`, `COGNATE_SSH_USER`, `COGNATE_SSH_KEY`).
+
+## Known limits
+
+Remote login shell must accept `exec sh -c '<posix script>'`. `version` is `mtime(seconds):size`. The
+symlink check is check-then-use (a concurrent swap between check and use is not prevented). No
+keyboard-interactive/2FA, no `@cert-authority`. See `.agents/DEBT.md` (DEBT-026).

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@godspeedai/cognate-execution-ssh",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "SSH host as an execution world: SFTP filesystem and remote exec over ssh2, with mandatory host-key verification, ProxyJump and clean disposal. Same contracts as every other provider.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GodSpeedAI/Cognate.git",
+    "directory": "packages/execution-ssh"
+  },
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./fixture": "./src/fixture.ts"
+  },
+  "dependencies": {
+    "@godspeedai/cognate-execution": "^0.1.0",
+    "ssh2": "1.17.0"
+  },
+  "devDependencies": {
+    "@types/ssh2": "^1.15.6"
+  }
+}

package/src/fixture.ts

@@ -0,0 +1,158 @@
+// A real SSH server (ssh2 `Server`) for deterministic tests: password/public-key auth, `exec` that
+// runs a real local shell, an SFTP subset backed by the real filesystem, and direct-tcpip forwarding
+// (so ProxyJump can be exercised). It is a test double for the *remote end only* — the provider
+// under test is the genuine client. Counters expose connection/session lifecycle for disposal tests.
+import { createServer as netServer, connect } from "node:net";
+import { promises as fsp, constants as fsc } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { Server, utils } from "ssh2";
+import type { Connection, ServerChannel } from "ssh2";
+import { fingerprintOf } from "./hostKeys.ts";
+
+const { STATUS_CODE, OPEN_MODE } = utils.sftp;
+
+export interface SshFixtureOptions {
+  readonly users: Readonly<Record<string, { readonly password?: string; readonly publicKeys?: readonly string[] }>>;
+  /** Reuse a host key (PEM) so a test can present a *different* identity on the same port. */
+  readonly hostKeyPem?: string;
+  /** Set to refuse `signal` requests like a server that ignores them. */
+  readonly ignoreSignals?: boolean;
+}
+
+export interface SshFixture {
+  readonly port: number;
+  readonly hostKeyPem: string;
+  readonly hostKeyBlob: Buffer;
+  readonly fingerprint: string;
+  readonly knownHostsLine: (host?: string) => string;
+  readonly stats: { connections: number; open: number; execs: number; sftp: number; sftpOpens: number; liveExecs: number };
+  dropConnections(): void;
+  close(): Promise<void>;
+}
+
+const attrsOf = (st: import("node:fs").Stats) => ({ mode: st.mode, uid: st.uid, gid: st.gid, size: st.size, atime: Math.floor(st.atimeMs / 1000), mtime: Math.floor(st.mtimeMs / 1000) });
+
+export async function startSshFixture(options: SshFixtureOptions): Promise<SshFixture> {
+  const generated = options.hostKeyPem ? undefined : utils.generateKeyPairSync("ed25519");
+  const hostKeyPem = options.hostKeyPem ?? generated!.private;
+  const parsed = utils.parseKey(hostKeyPem);
+  if (parsed instanceof Error) throw parsed;
+  const hostKeyBlob = parsed.getPublicSSH();
+  const stats = { connections: 0, open: 0, execs: 0, sftp: 0, sftpOpens: 0, liveExecs: 0 };
+  const conns = new Set<Connection>();
+  const sockets = new Set<import("node:net").Socket>();
+
+  const server = new Server({ hostKeys: [hostKeyPem] }, (client) => {
+    stats.connections++; stats.open++; conns.add(client);
+    client.on("close", () => { stats.open--; conns.delete(client); });
+    client.on("error", () => {});
+    client.on("authentication", (ctx) => {
+      const user = options.users[ctx.username];
+      if (!user) return ctx.reject();
+      if (ctx.method === "password" && user.password !== undefined && ctx.password === user.password) return ctx.accept();
+      if (ctx.method === "publickey" && user.publicKeys) {
+        const offered = ctx.key;
+        const ok = user.publicKeys.some((k) => { const p = utils.parseKey(k); return !(p instanceof Error) && p.getPublicSSH().equals(offered.data); });
+        if (ok && (!ctx.signature || ctx.blob)) {
+          if (!ctx.signature) return ctx.accept();
+          const p = utils.parseKey(user.publicKeys.find((k) => { const q = utils.parseKey(k); return !(q instanceof Error) && q.getPublicSSH().equals(offered.data); })!);
+          if (!(p instanceof Error) && p.verify(ctx.blob!, ctx.signature, ctx.hashAlgo as never) === true) return ctx.accept();
+        }
+      }
+      return ctx.reject(["password", "publickey"]);
+    });
+    client.on("ready", () => {
+      client.on("session", (accept) => {
+        const session = accept();
+        let child: ReturnType<typeof Bun.spawn> | undefined;
+        session.on("signal", (acc) => { acc?.(); if (!options.ignoreSignals) child?.kill(); });
+        session.on("exec", (acc, _rej, info) => {
+          const channel: ServerChannel = acc();
+          stats.execs++; stats.liveExecs++;
+          const proc = Bun.spawn(["sh", "-c", info.command], { stdout: "pipe", stderr: "pipe", stdin: "pipe" });
+          child = proc;
+          const stdin = proc.stdin;
+          channel.on("data", (d: Buffer) => { try { stdin.write(d); } catch { /* child gone */ } });
+          // Like sshd without a pty: channel EOF/close closes the command's stdin; it does NOT kill it.
+          const closeStdin = () => { try { void stdin.end(); } catch { /* already closed */ } };
+          channel.on("end", closeStdin); channel.on("close", closeStdin);
+          const pump = async (src: ReadableStream<Uint8Array>, write: (b: Buffer) => void) => { for await (const c of src) write(Buffer.from(c)); };
+          void Promise.all([pump(child.stdout as ReadableStream<Uint8Array>, (b) => channel.write(b)), pump(child.stderr as ReadableStream<Uint8Array>, (b) => channel.stderr.write(b))]).then(async () => {
+            const code = await child!.exited;
+            stats.liveExecs--;
+            try { channel.exit(code ?? 255); channel.end(); } catch { /* channel gone */ }
+          });
+        });
+        session.on("sftp", (acc) => { stats.sftp++; serveSftp(acc(), stats); });
+      });
+      client.on("tcpip", (acc, rej, info) => {
+        const sock = connect(info.destPort, info.destIP);
+        sockets.add(sock);
+        sock.once("error", () => rej());
+        sock.once("connect", () => { const ch = acc(); ch.pipe(sock).pipe(ch); ch.on("close", () => sock.destroy()); });
+        sock.on("close", () => sockets.delete(sock));
+      });
+    });
+  });
+  await new Promise<void>((res) => server.listen(0, "127.0.0.1", res));
+  const port = (server.address() as { port: number }).port;
+  return {
+    port, hostKeyPem, hostKeyBlob, fingerprint: fingerprintOf(hostKeyBlob), stats,
+    knownHostsLine: (host = "127.0.0.1") => `[${host}]:${port} ${parsed.type} ${hostKeyBlob.toString("base64")}`,
+    dropConnections() { for (const c of conns) c.end(); for (const s of sockets) s.destroy(); },
+    async close() { for (const c of conns) c.end(); for (const s of sockets) s.destroy(); await new Promise<void>((r) => server.close(() => r())); },
+  };
+}
+
+function serveSftp(sftp: import("ssh2").SFTPWrapper, stats: { sftpOpens: number }): void {
+  type H = { kind: "file"; fd: import("node:fs/promises").FileHandle } | { kind: "dir"; entries: string[]; path: string; done: boolean };
+  const handles = new Map<number, H>();
+  let next = 1;
+  const handleBuf = (id: number) => { const b = Buffer.alloc(4); b.writeUInt32BE(id); return b; };
+  const idOf = (b: Buffer) => b.readUInt32BE(0);
+  const fail = (reqid: number, e: unknown) => sftp.status(reqid, (e as NodeJS.ErrnoException)?.code === "ENOENT" ? STATUS_CODE.NO_SUCH_FILE : (e as NodeJS.ErrnoException)?.code === "EACCES" ? STATUS_CODE.PERMISSION_DENIED : STATUS_CODE.FAILURE);
+  const ok = (reqid: number) => sftp.status(reqid, STATUS_CODE.OK);
+
+  sftp.on("REALPATH", async (reqid, path) => {
+    try { const real = await fsp.realpath(path); sftp.name(reqid, [{ filename: real, longname: real, attrs: {} as never }]); } catch (e) { fail(reqid, e); }
+  });
+  const doStat = (follow: boolean) => async (reqid: number, path: string) => {
+    try { const st = await (follow ? fsp.stat(path) : fsp.lstat(path)); sftp.attrs(reqid, attrsOf(st) as never); } catch (e) { fail(reqid, e); }
+  };
+  sftp.on("STAT", doStat(true)); sftp.on("LSTAT", doStat(false));
+  sftp.on("FSTAT", async (reqid, h) => { const e = handles.get(idOf(h)); if (e?.kind !== "file") return sftp.status(reqid, STATUS_CODE.FAILURE); try { sftp.attrs(reqid, attrsOf(await e.fd.stat()) as never); } catch (er) { fail(reqid, er); } });
+  sftp.on("OPEN", async (reqid, path, flags) => {
+    stats.sftpOpens++;
+    try {
+      let f = 0;
+      if ((flags & OPEN_MODE.READ) && (flags & OPEN_MODE.WRITE)) f = fsc.O_RDWR; else if (flags & OPEN_MODE.WRITE) f = fsc.O_WRONLY; else f = fsc.O_RDONLY;
+      if (flags & OPEN_MODE.CREAT) f |= fsc.O_CREAT; if (flags & OPEN_MODE.TRUNC) f |= fsc.O_TRUNC; if (flags & OPEN_MODE.EXCL) f |= fsc.O_EXCL; if (flags & OPEN_MODE.APPEND) f |= fsc.O_APPEND;
+      const fd = await fsp.open(path, f, 0o644);
+      const id = next++; handles.set(id, { kind: "file", fd }); sftp.handle(reqid, handleBuf(id));
+    } catch (e) { fail(reqid, e); }
+  });
+  sftp.on("READ", async (reqid, h, offset, length) => {
+    const e = handles.get(idOf(h)); if (e?.kind !== "file") return sftp.status(reqid, STATUS_CODE.FAILURE);
+    try { const buf = Buffer.alloc(length); const { bytesRead } = await e.fd.read(buf, 0, length, offset); if (bytesRead === 0) sftp.status(reqid, STATUS_CODE.EOF); else sftp.data(reqid, buf.subarray(0, bytesRead)); } catch (er) { fail(reqid, er); }
+  });
+  sftp.on("WRITE", async (reqid, h, offset, data) => {
+    const e = handles.get(idOf(h)); if (e?.kind !== "file") return sftp.status(reqid, STATUS_CODE.FAILURE);
+    try { await e.fd.write(data, 0, data.length, offset); ok(reqid); } catch (er) { fail(reqid, er); }
+  });
+  sftp.on("CLOSE", async (reqid, h) => { const e = handles.get(idOf(h)); handles.delete(idOf(h)); if (e?.kind === "file") await e.fd.close().catch(() => {}); ok(reqid); });
+  sftp.on("OPENDIR", async (reqid, path) => { try { const entries = await fsp.readdir(path); const id = next++; handles.set(id, { kind: "dir", entries, path, done: false }); sftp.handle(reqid, handleBuf(id)); } catch (e) { fail(reqid, e); } });
+  sftp.on("READDIR", async (reqid, h) => {
+    const e = handles.get(idOf(h)); if (e?.kind !== "dir" || e.done) return sftp.status(reqid, STATUS_CODE.EOF);
+    e.done = true;
+    const names = await Promise.all(e.entries.map(async (n) => ({ filename: n, longname: n, attrs: attrsOf(await fsp.lstat(resolve(e.path, n))) as never })));
+    sftp.name(reqid, names);
+  });
+  sftp.on("MKDIR", async (reqid, path) => { try { await fsp.mkdir(path); ok(reqid); } catch (e) { fail(reqid, e); } });
+  sftp.on("REMOVE", async (reqid, path) => { try { await fsp.unlink(path); ok(reqid); } catch (e) { fail(reqid, e); } });
+  sftp.on("RMDIR", async (reqid, path) => { try { await fsp.rmdir(path); ok(reqid); } catch (e) { fail(reqid, e); } });
+  sftp.on("RENAME", async (reqid, a, b) => { try { await fsp.mkdir(dirname(b), { recursive: true }); await fsp.rename(a, b); ok(reqid); } catch (e) { fail(reqid, e); } });
+  sftp.on("SETSTAT", (reqid) => ok(reqid)); sftp.on("FSETSTAT", (reqid) => ok(reqid));
+  sftp.on("end", () => { for (const e of handles.values()) if (e.kind === "file") void e.fd.close().catch(() => {}); handles.clear(); });
+}
+
+export { netServer };

package/src/hostKeys.ts

@@ -0,0 +1,80 @@
+// Host identity verification. A connection is refused unless the server's key matches an expected
+// SHA-256 fingerprint or an OpenSSH `known_hosts` entry; there is no trust-on-first-use and no
+// "accept anything" mode. Hashed (`|1|salt|hash`) and plain entries, `[host]:port`, wildcards,
+// negation and `@revoked` are honoured; `@cert-authority` entries are ignored (not supported).
+import { createHash, createHmac } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+export interface HostKeyPolicy {
+  /** Accept exactly these `SHA256:<base64>` fingerprints (as printed by `ssh-keygen -lf`). */
+  readonly fingerprints?: readonly string[];
+  /** OpenSSH known_hosts file contents. */
+  readonly knownHosts?: string;
+  /** Path to an OpenSSH known_hosts file, read at connect time. */
+  readonly knownHostsPath?: string;
+}
+
+export function fingerprintOf(key: Buffer): string {
+  return `SHA256:${createHash("sha256").update(key).digest("base64").replace(/=+$/, "")}`;
+}
+
+export function policyIsEmpty(policy: HostKeyPolicy): boolean {
+  return !(policy.fingerprints?.length || policy.knownHosts || policy.knownHostsPath);
+}
+
+function wildcard(pattern: string, value: string): boolean {
+  const re = new RegExp(`^${pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".")}$`);
+  return re.test(value);
+}
+
+function hostMatches(field: string, names: readonly string[]): boolean {
+  if (field.startsWith("|1|")) {
+    const [, , salt, hash] = field.split("|");
+    if (!salt || !hash) return false;
+    const saltBytes = Buffer.from(salt, "base64");
+    return names.some((n) => createHmac("sha1", saltBytes).update(n).digest("base64") === hash);
+  }
+  let matched = false;
+  for (const raw of field.split(",")) {
+    const negated = raw.startsWith("!");
+    const hit = names.some((n) => wildcard(negated ? raw.slice(1) : raw, n));
+    if (hit && negated) return false;
+    if (hit) matched = true;
+  }
+  return matched;
+}
+
+/** Returns "trusted" | "revoked" | "unknown" for one server key against known_hosts text. */
+export function checkKnownHosts(text: string, host: string, port: number, key: Buffer): "trusted" | "revoked" | "unknown" {
+  const names = port === 22 ? [host, `[${host}]:22`] : [`[${host}]:${port}`];
+  const b64 = key.toString("base64");
+  let trusted = false;
+  for (const line of text.split("\n")) {
+    const t = line.trim();
+    if (!t || t.startsWith("#")) continue;
+    const parts = t.split(/\s+/);
+    let marker: string | undefined;
+    if (parts[0]!.startsWith("@")) marker = parts.shift();
+    if (marker === "@cert-authority") continue;
+    const [hosts, , keyB64] = parts;
+    if (!hosts || !keyB64 || keyB64 !== b64 || !hostMatches(hosts, names)) continue;
+    if (marker === "@revoked") return "revoked";
+    trusted = true;
+  }
+  return trusted ? "trusted" : "unknown";
+}
+
+export function verifyHostKey(policy: HostKeyPolicy, host: string, port: number, key: Buffer): boolean {
+  const text = policy.knownHosts ?? (policy.knownHostsPath ? safeRead(policy.knownHostsPath) : undefined);
+  const known = text === undefined ? "unknown" : checkKnownHosts(text, host, port, key);
+  if (known === "revoked") return false; // a revoked key is never accepted, even if pinned elsewhere
+  return known === "trusted" || policy.fingerprints?.includes(fingerprintOf(key)) === true;
+}
+
+function safeRead(path: string): string | undefined {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return undefined;
+  }
+}

package/src/index.ts

@@ -0,0 +1,323 @@
+// An SSH host as an execution world (ssh2). Files go over SFTP, commands over `exec`. Everything
+// the contracts promise holds here: containment at `resolve` plus a symlink-safe check before each
+// file operation; a missing path is `undefined`; timeouts and aborts end the remote command; and the
+// world FAILS CLOSED — an unreachable host, a changed host key or a disposed world raises
+// WorldUnavailableError and nothing ever falls back to local execution.
+//
+// Mechanism only is borrowed from the studied donor (connection reuse, lazy SFTP, ProxyJump via
+// forwardOut); the code is original and, unlike the donor, host-key verification is mandatory.
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { Client } from "ssh2";
+import type { ClientChannel, ConnectConfig, SFTPWrapper } from "ssh2";
+import { PathEscapeError, WorldUnavailableError, createRootGuard, shellQuote, supervisedExecScript } from "@godspeedai/cognate-execution";
+import type { DirEntry, ExecResult, ExecSpec, ExecutionWorldProvider, FileStat } from "@godspeedai/cognate-execution";
+import { checkKnownHosts, fingerprintOf, policyIsEmpty, verifyHostKey } from "./hostKeys.ts";
+import type { HostKeyPolicy } from "./hostKeys.ts";
+
+export { fingerprintOf, checkKnownHosts, verifyHostKey } from "./hostKeys.ts";
+export type { HostKeyPolicy } from "./hostKeys.ts";
+
+export type SshAuth =
+  | { readonly kind: "password"; readonly password: string }
+  | { readonly kind: "key"; readonly privateKey?: string; readonly privateKeyPath?: string; readonly passphrase?: string }
+  | { readonly kind: "agent"; readonly socket?: string };
+
+export interface SshHop {
+  readonly host: string;
+  readonly port?: number;
+  readonly username: string;
+  readonly auth: SshAuth;
+  readonly hostKeys: HostKeyPolicy;
+}
+
+export interface SshWorldOptions extends SshHop {
+  readonly worldId: string;
+  /** Intermediate hosts, outermost first (ProxyJump). Each hop is verified like the target. */
+  readonly jump?: readonly SshHop[];
+  readonly readyTimeoutMs?: number;
+  readonly keepaliveMs?: number;
+  readonly defaultTimeoutMs?: number;
+  readonly maxOutputBytes?: number;
+}
+
+/** The server's identity did not match the configured policy. Never retried, never bypassed. */
+export class HostKeyMismatchError extends WorldUnavailableError {
+  override readonly name = "HostKeyMismatchError";
+  constructor(worldId: string, readonly host: string, readonly offered: string) {
+    super(worldId, `host key for ${host} (${offered}) does not match the configured host-key policy`);
+  }
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_OUTPUT = 10 * 1024 * 1024;
+const NO_SUCH_FILE = 2;
+
+function expandHome(path: string): string {
+  return path === "~" || path.startsWith("~/") ? join(homedir(), path.slice(1)) : path;
+}
+
+function authConfig(auth: SshAuth): Partial<ConnectConfig> {
+  switch (auth.kind) {
+    case "password": return { password: auth.password };
+    case "key": {
+      const privateKey = auth.privateKey ?? (auth.privateKeyPath ? readFileSync(expandHome(auth.privateKeyPath), "utf8") : undefined);
+      if (!privateKey) throw new Error("ssh key auth needs privateKey or privateKeyPath");
+      return { privateKey, ...(auth.passphrase ? { passphrase: auth.passphrase } : {}) };
+    }
+    case "agent": {
+      const agent = auth.socket ?? process.env.SSH_AUTH_SOCK;
+      if (!agent) throw new Error("ssh agent auth needs a socket (SSH_AUTH_SOCK is unset)");
+      return { agent };
+    }
+  }
+}
+
+function connectReady(client: Client, config: ConnectConfig): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    const done = () => { client.removeListener("error", fail); resolve(); };
+    const fail = (e: Error) => { client.removeListener("ready", done); reject(e); };
+    client.once("ready", done);
+    client.once("error", fail);
+    client.connect(config);
+  });
+}
+
+const call = <T>(fn: (cb: (err: Error | null | undefined, value: T) => void) => void): Promise<T> =>
+  new Promise<T>((resolve, reject) => fn((err, value) => (err ? reject(err) : resolve(value))));
+
+export function sshExecutionWorld(options: SshWorldOptions): ExecutionWorldProvider {
+  const { worldId } = options;
+  const port = options.port ?? 22;
+  const maxOut = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT;
+  const hops: readonly SshHop[] = [...(options.jump ?? []), options];
+  for (const hop of hops) if (policyIsEmpty(hop.hostKeys)) throw new Error(`ssh world ${worldId}: a host-key policy (fingerprints or known_hosts) is required for ${hop.host}`);
+
+  let disposed = false;
+  let clients: Client[] = [];
+  let opening: Promise<Client> | undefined;
+  let sftpOpening: Promise<SFTPWrapper> | undefined;
+  let sftp: SFTPWrapper | undefined;
+  let observedFingerprint: string | undefined;
+  const channels = new Set<ClientChannel>();
+
+  const closed = (): never => { throw new WorldUnavailableError(worldId, "execution world is disposed"); };
+
+  function invalidate(): void {
+    const old = clients;
+    clients = []; opening = undefined; sftpOpening = undefined; sftp = undefined;
+    for (const c of old.reverse()) try { c.end(); } catch { /* already closed */ }
+  }
+
+  async function open(): Promise<Client> {
+    const made: Client[] = [];
+    try {
+      for (let i = 0; i < hops.length; i++) {
+        const hop = hops[i]!;
+        const hopPort = hop.port ?? (hop === options ? port : 22);
+        const client = new Client();
+        client.on("error", () => { /* surfaced via connectReady / invalidate; never an uncaught process error */ });
+        made.push(client);
+        let mismatch: string | undefined;
+        const config: ConnectConfig = {
+          host: hop.host, port: hopPort, username: hop.username,
+          readyTimeout: options.readyTimeoutMs ?? 20_000,
+          keepaliveInterval: options.keepaliveMs ?? 15_000, keepaliveCountMax: 3,
+          ...authConfig(hop.auth),
+          hostVerifier: (key: Buffer) => {
+            const ok = verifyHostKey(hop.hostKeys, hop.host, hopPort, key);
+            if (!ok) mismatch = fingerprintOf(key);
+            else if (i === hops.length - 1) observedFingerprint = fingerprintOf(key);
+            return ok;
+          },
+        };
+        const prev = made[i - 1];
+        try {
+          if (!prev) await connectReady(client, config);
+          else {
+            const sock = await call<NodeJS.ReadableStream & NodeJS.WritableStream>((cb) => prev.forwardOut("127.0.0.1", 0, hop.host, hopPort, cb as never));
+            await connectReady(client, { ...config, sock: sock as never });
+          }
+        } catch (e) {
+          if (mismatch) throw new HostKeyMismatchError(worldId, hop.host, mismatch);
+          throw e;
+        }
+      }
+      const target = made[made.length - 1]!;
+      clients = made;
+      target.on("close", () => { if (clients[clients.length - 1] === target) invalidate(); });
+      target.on("error", () => { if (clients[clients.length - 1] === target) invalidate(); });
+      return target;
+    } catch (e) {
+      for (const c of made.reverse()) try { c.end(); } catch { /* best effort */ }
+      throw e instanceof WorldUnavailableError ? e : new WorldUnavailableError(worldId, `cannot connect to ${options.username}@${options.host}:${port}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+
+  async function getClient(): Promise<Client> {
+    if (disposed) closed();
+    opening ??= open().catch((e) => { opening = undefined; throw e; });
+    const c = await opening;
+    if (disposed) closed();
+    return c;
+  }
+
+  async function getSftp(): Promise<SFTPWrapper> {
+    if (sftp) return sftp;
+    sftpOpening ??= (async () => {
+      const client = await getClient();
+      const s = await call<SFTPWrapper>((cb) => client.sftp(cb as never));
+      const drop = () => { if (sftp === s) { sftp = undefined; sftpOpening = undefined; } };
+      s.on("close", drop); s.on("end", drop);
+      sftp = s;
+      return s;
+    })().catch((e) => { sftpOpening = undefined; throw e instanceof WorldUnavailableError ? e : new WorldUnavailableError(worldId, `sftp unavailable: ${e instanceof Error ? e.message : String(e)}`); });
+    return sftpOpening;
+  }
+
+  const isConnectionError = (e: unknown) => e instanceof Error && /not connected|no sftp connection|channel (closed|open failure)|ECONNRESET|socket/i.test(e.message) && !(e instanceof WorldUnavailableError);
+  /** Idempotent operations get exactly one transparent reconnect; anything else surfaces the failure. */
+  async function withSftp<T>(fn: (s: SFTPWrapper) => Promise<T>): Promise<T> {
+    if (disposed) closed();
+    try {
+      return await fn(await getSftp());
+    } catch (e) {
+      if (!isConnectionError(e)) throw e;
+      invalidate();
+      return fn(await getSftp());
+    }
+  }
+
+  const statRaw = (path: string) => withSftp(async (s) => {
+    try { return await call<import("ssh2").Stats>((cb) => s.stat(path, cb as never)); }
+    catch (e) { if ((e as { code?: number }).code === NO_SUCH_FILE) return undefined; throw e; }
+  });
+  const realpath = (path: string) => withSftp(async (s) => {
+    try { return await call<string>((cb) => s.realpath(path, cb as never)); }
+    catch (e) { if ((e as { code?: number }).code === NO_SUCH_FILE) return undefined; throw e; }
+  });
+  const guard = createRootGuard(realpath);
+  const kindOf = (st: { isFile(): boolean; isDirectory(): boolean }): FileStat["kind"] => (st.isFile() ? "file" : st.isDirectory() ? "directory" : "other");
+  const versionOf = (st: { size: number; mtime: number }) => `${st.mtime}:${st.size}`;
+
+  async function exec(spec: ExecSpec, o?: { readonly signal?: AbortSignal }): Promise<ExecResult> {
+    const client = await getClient();
+    const command = `exec sh -c ${shellQuote(supervisedExecScript(spec.argv, spec.cwd, spec.env))}`;
+    return new Promise<ExecResult>((resolve, reject) => {
+      let timedOut = false;
+      let stream: ClientChannel | undefined;
+      let settled = false;
+      const out: Buffer[] = []; const err: Buffer[] = [];
+      let outSize = 0; let errSize = 0;
+      const kill = () => {
+        if (!stream) return;
+        // TERM reaches the supervisor (which ends the command's process group); closing the channel
+        // is the fallback for servers that ignore signal requests: stdin EOF triggers the same cleanup.
+        try { stream.signal("TERM"); } catch { /* server may ignore signals */ }
+        try { stream.close(); } catch { /* already closed */ }
+      };
+      const timer = setTimeout(() => { timedOut = true; kill(); }, spec.timeoutMs ?? options.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS);
+      const onAbort = () => kill();
+      const finish = (r: ExecResult) => {
+        if (settled) return;
+        settled = true; clearTimeout(timer); o?.signal?.removeEventListener("abort", onAbort);
+        if (stream) channels.delete(stream);
+        resolve(r);
+      };
+      client.exec(command, { pty: false }, (e, s) => {
+        if (e) { clearTimeout(timer); reject(new WorldUnavailableError(worldId, `exec failed: ${e.message}`)); return; }
+        stream = s; channels.add(s);
+        s.on("data", (d: Buffer) => { if (outSize < maxOut) { out.push(d); outSize += d.length; } });
+        s.stderr.on("data", (d: Buffer) => { if (errSize < maxOut) { err.push(d); errSize += d.length; } });
+        s.on("close", (code: number | null) => finish({ stdout: Buffer.concat(out).subarray(0, maxOut).toString("utf8"), stderr: Buffer.concat(err).subarray(0, maxOut).toString("utf8"), exitCode: code ?? -1, timedOut }));
+        if (o?.signal?.aborted) kill(); else o?.signal?.addEventListener("abort", onAbort, { once: true });
+      });
+    });
+  }
+
+  return {
+    worldId,
+    kind: "ssh",
+    get metadata() {
+      return {
+        host: options.host, port: String(port), username: options.username, auth: options.auth.kind,
+        ...(options.jump?.length ? { jump: options.jump.map((h) => `${h.username}@${h.host}`).join(",") } : {}),
+        ...(observedFingerprint ? { hostKey: observedFingerprint } : {}),
+      };
+    },
+    fileSystem: {
+      resolve: (root, path) => guard.resolve(root, path),
+      async stat(path): Promise<FileStat | undefined> {
+        await guard.assertContained(path);
+        const st = await statRaw(path);
+        return st ? { kind: kindOf(st), size: st.size, version: versionOf(st) } : undefined;
+      },
+      async exists(path) { await guard.assertContained(path); return (await statRaw(path)) !== undefined; },
+      async version(path) { await guard.assertContained(path); const st = await statRaw(path); return st ? versionOf(st) : undefined; },
+      async readText(path) {
+        await guard.assertContained(path);
+        return withSftp(async (s) => (await call<Buffer>((cb) => s.readFile(path, cb as never))).toString("utf8"));
+      },
+      async list(path): Promise<readonly DirEntry[]> {
+        await guard.assertContained(path);
+        return withSftp(async (s) => (await call<{ filename: string; attrs: { isFile(): boolean; isDirectory(): boolean } }[]>((cb) => s.readdir(path, cb as never)))
+          .filter((e) => e.filename !== "." && e.filename !== "..")
+          .map((e) => ({ name: e.filename, kind: kindOf(e.attrs) })));
+      },
+      async writeText(path, content) {
+        await guard.assertContained(path);
+        if (disposed) closed();
+        // Writes are not retried: a half-completed write must surface, not repeat.
+        const s = await getSftp();
+        await call<void>((cb) => s.writeFile(path, Buffer.from(content, "utf8"), cb as never));
+      },
+    },
+    process: { exec },
+    async dispose() {
+      if (disposed) return;
+      disposed = true;
+      for (const ch of channels) try { ch.close(); } catch { /* closing */ }
+      channels.clear();
+      if (sftp) try { sftp.end(); } catch { /* closing */ }
+      invalidate();
+    },
+  };
+}
+
+export { PathEscapeError };
+
+export interface HostKeyProbe {
+  readonly fingerprint: string;
+  readonly keyType: string;
+  /** Whether the key is already trusted in the given known_hosts text (never decides trust by itself). */
+  readonly known?: "trusted" | "unknown" | "revoked";
+}
+
+/**
+ * Reads a server's host key and stops: the verifier records the key and then REFUSES it, so nothing
+ * is ever authenticated or sent. The caller shows the fingerprint to a human, who decides whether to
+ * pin it; trust is a human act, never a side effect of connecting.
+ */
+export function probeHostKey(options: { readonly host: string; readonly port?: number; readonly timeoutMs?: number; readonly knownHosts?: string }): Promise<HostKeyProbe> {
+  const port = options.port ?? 22;
+  return new Promise((resolve, reject) => {
+    const client = new Client();
+    let seen: Buffer | undefined;
+    let settled = false;
+    const finish = (fn: () => void) => { if (settled) return; settled = true; try { client.end(); } catch { /* closing */ } fn(); };
+    client.on("error", (e) => finish(() => {
+      if (seen) resolve(describe(seen));
+      else reject(new Error(`cannot reach ${options.host}:${port}: ${e.message}`));
+    }));
+    const describe = (key: Buffer): HostKeyProbe => {
+      const typeLength = key.readUInt32BE(0);
+      return {
+        fingerprint: fingerprintOf(key),
+        keyType: key.subarray(4, 4 + typeLength).toString("ascii"),
+        ...(options.knownHosts === undefined ? {} : { known: checkKnownHosts(options.knownHosts, options.host, port, key) }),
+      };
+    };
+    client.connect({ host: options.host, port, username: "cognate-probe", readyTimeout: options.timeoutMs ?? 10_000, hostVerifier: (key: Buffer) => { seen = key; return false; } });
+  });
+}