@patimweb/pi-ssh 1.0.0

package/src/doctor.ts

@@ -0,0 +1,212 @@
+/**
+ * Environment report.
+ *
+ * The point of this module is to answer "what do I have to install to use
+ * this?" with evidence rather than a guess. The short answer is nothing:
+ * ssh2 is a pure JavaScript SSH implementation and keys are generated in
+ * process, so no `ssh`, `ssh-keygen` or `ssh-copy-id` binary is required on
+ * any platform. What the checks below find are the optional conveniences and
+ * the two things that genuinely do break a connection: an unreadable key file
+ * and a known_hosts that cannot be written.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { defaultKnownHostsPath } from "./known-hosts.ts";
+
+export type CheckStatus = "ok" | "note" | "problem";
+
+export interface Check {
+  readonly name: string;
+  readonly status: CheckStatus;
+  readonly detail: string;
+  /** What to do about it, when there is something to do. */
+  readonly remedy?: string;
+}
+
+function checkNodeVersion(): Check {
+  const major = Number.parseInt(process.versions.node.split(".")[0], 10);
+  return major >= 20
+    ? { name: "Node", status: "ok", detail: `v${process.versions.node}` }
+    : {
+        name: "Node",
+        status: "problem",
+        detail: `v${process.versions.node} is older than this extension supports`,
+        remedy: "Run pi on Node 20 or newer.",
+      };
+}
+
+function checkSsh2(): Check {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(
+        new URL("../node_modules/ssh2/package.json", import.meta.url),
+        "utf8",
+      ),
+    );
+    return {
+      name: "SSH implementation",
+      status: "ok",
+      detail: `ssh2 ${pkg.version}, pure JavaScript -- no ssh binary needed`,
+    };
+  } catch {
+    return {
+      name: "SSH implementation",
+      status: "ok",
+      detail: "ssh2 (bundled dependency), pure JavaScript -- no ssh binary needed",
+    };
+  }
+}
+
+function checkKeyGeneration(): Check {
+  return {
+    name: "Key generation",
+    status: "ok",
+    detail: "ed25519 keys are generated in process; ssh-keygen is not required",
+  };
+}
+
+function checkSshDirectory(): Check {
+  const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+  const dir = path.join(home, ".ssh");
+
+  if (!fs.existsSync(dir)) {
+    return {
+      name: "~/.ssh",
+      status: "note",
+      detail: `${dir} does not exist yet; it will be created when first needed`,
+    };
+  }
+
+  // Permissions only matter on POSIX; Windows uses ACLs and reports 0666.
+  if (process.platform !== "win32") {
+    const mode = fs.statSync(dir).mode & 0o777;
+    if (mode & 0o077) {
+      return {
+        name: "~/.ssh",
+        status: "note",
+        detail: `${dir} is group- or world-accessible (mode ${mode.toString(8)})`,
+        remedy: `chmod 700 ${dir} -- OpenSSH refuses some keys otherwise.`,
+      };
+    }
+  }
+  return { name: "~/.ssh", status: "ok", detail: dir };
+}
+
+function checkKnownHosts(): Check {
+  const file = defaultKnownHostsPath();
+  if (!fs.existsSync(file)) {
+    return {
+      name: "known_hosts",
+      status: "note",
+      detail: `${file} does not exist; the first connection to each host will have to be confirmed`,
+    };
+  }
+  try {
+    fs.accessSync(file, fs.constants.R_OK | fs.constants.W_OK);
+  } catch {
+    return {
+      name: "known_hosts",
+      status: "problem",
+      detail: `${file} is not readable and writable`,
+      remedy: "Host keys cannot be verified or recorded until that is fixed.",
+    };
+  }
+  const lines = fs
+    .readFileSync(file, "utf-8")
+    .split(/\r?\n/)
+    .filter((line) => line.trim() && !line.startsWith("#")).length;
+  return {
+    name: "known_hosts",
+    status: "ok",
+    detail: `${file} (${lines} host${lines === 1 ? "" : "s"} on record)`,
+  };
+}
+
+function checkConfigDirectory(): Check {
+  const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+  const dir = path.join(home, ".pi");
+  const file = path.join(dir, "ssh-config.json");
+
+  if (!fs.existsSync(file)) {
+    return { name: "Stored hosts", status: "note", detail: "no hosts configured yet" };
+  }
+  if (process.platform !== "win32") {
+    const mode = fs.statSync(file).mode & 0o777;
+    if (mode !== 0o600) {
+      return {
+        name: "Stored hosts",
+        status: "problem",
+        detail: `${file} has mode ${mode.toString(8)} and may contain passwords`,
+        remedy: `chmod 600 ${file}`,
+      };
+    }
+  }
+  return { name: "Stored hosts", status: "ok", detail: `${file} (owner only)` };
+}
+
+/**
+ * Is an `ssh` command available? Purely informational: this extension does
+ * not use it, but a user who wants to reuse a generated key from a terminal
+ * will want to know.
+ */
+function checkOpenSshClient(): Check {
+  const dirs = (process.env.PATH ?? "").split(path.delimiter).filter(Boolean);
+  const names = process.platform === "win32" ? ["ssh.exe"] : ["ssh"];
+
+  for (const dir of dirs) {
+    for (const name of names) {
+      try {
+        const candidate = path.join(dir, name);
+        if (fs.existsSync(candidate)) {
+          return {
+            name: "OpenSSH client (optional)",
+            status: "ok",
+            detail: `${candidate} -- keys made here work with it too`,
+          };
+        }
+      } catch {
+        /* an unreadable PATH entry is not interesting */
+      }
+    }
+  }
+
+  return {
+    name: "OpenSSH client (optional)",
+    status: "note",
+    detail: "no ssh command on PATH",
+    remedy:
+      process.platform === "win32"
+        ? "Not needed by this extension. To use keys from a terminal too: Settings -> Apps -> Optional features -> OpenSSH Client."
+        : "Not needed by this extension. Install the openssh-client package if you also want to ssh by hand.",
+  };
+}
+
+export function runChecks(): Check[] {
+  return [
+    checkNodeVersion(),
+    checkSsh2(),
+    checkKeyGeneration(),
+    checkOpenSshClient(),
+    checkSshDirectory(),
+    checkKnownHosts(),
+    checkConfigDirectory(),
+  ];
+}
+
+export function formatChecks(checks: ReadonlyArray<Check>): string {
+  const symbol = { ok: "ok  ", note: "note", problem: "FAIL" } as const;
+  const lines = checks.map((check) => {
+    const head = `[${symbol[check.status]}] ${check.name}: ${check.detail}`;
+    return check.remedy ? `${head}\n         ${check.remedy}` : head;
+  });
+
+  const problems = checks.filter((check) => check.status === "problem").length;
+  const summary =
+    problems > 0
+      ? `${problems} problem(s) need attention before this will work reliably.`
+      : "Nothing needs to be installed: this extension speaks SSH itself and generates its own keys.";
+
+  return [`Environment (${process.platform}, ${process.arch}):`, ...lines, "", summary].join("\n");
+}

package/src/formatting/formatters.ts

@@ -0,0 +1,133 @@
+/**
+ * Output formatters.
+ *
+ * Pure functions that transform domain data into display strings.
+ * No emojis, no side effects.
+ */
+
+import type {
+  AuthorizeResult,
+  ExecResult,
+  RemoteEntry,
+  ServerIdentity,
+  SshProfile,
+  TransferResult,
+} from "../types.ts";
+
+export function formatBytes(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes < 0) return "unknown size";
+  if (bytes < 1024) return `${bytes} B`;
+  const units = ["KB", "MB", "GB", "TB"];
+  let value = bytes / 1024;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  return `${value.toFixed(value >= 10 ? 0 : 1)} ${units[unit]}`;
+}
+
+/** How a profile authenticates, without revealing any secret. */
+export function describeAuth(profile: SshProfile): string {
+  const methods: string[] = [];
+  if (profile.privateKeyPath) methods.push(`key ${profile.privateKeyPath}`);
+  if (profile.password) methods.push("password (stored)");
+  return methods.length > 0 ? methods.join(", ") : "none configured";
+}
+
+export function formatProfileStatus(
+  profiles: Record<string, SshProfile>,
+  active: string | null,
+): string {
+  const names = Object.keys(profiles);
+  if (names.length === 0) {
+    return "No SSH hosts configured. Use ssh_setup with a host, user, and a password or key path.";
+  }
+
+  const lines: string[] = [];
+  for (const name of names) {
+    const profile = profiles[name];
+    const marker = name === active ? "*" : " ";
+    const port = profile.port === 22 ? "" : `:${profile.port}`;
+    lines.push(`${marker} ${name}: ${profile.user}@${profile.host}${port}`);
+    lines.push(`    auth: ${describeAuth(profile)}`);
+    if (profile.strictHostKey === false) {
+      lines.push("    host key checking is OFF for this profile");
+    }
+  }
+
+  return [`SSH hosts (${names.length}), * marks the active one:`, ...lines].join("\n");
+}
+
+export function formatIdentity(identity: ServerIdentity): string {
+  return [
+    `Connected: ${identity.user}@${identity.host}:${identity.port}`,
+    `Authenticated with: ${identity.authMethod}`,
+    `Host key: ${identity.keyType} ${identity.fingerprint} (${identity.hostKeyVerdict})`,
+  ].join("\n");
+}
+
+export function formatExecResult(result: ExecResult): string {
+  const sections: string[] = [];
+  const status =
+    result.code === 0
+      ? "exit 0"
+      : result.signal
+        ? `killed by ${result.signal}`
+        : `exit ${result.code}`;
+
+  sections.push(`$ ${result.command}`);
+  sections.push(`[${status}, ${result.durationMs} ms]`);
+
+  if (result.stdout.trim()) {
+    sections.push("", result.stdout.replace(/\s+$/, ""));
+  }
+  if (result.stderr.trim()) {
+    sections.push("", "stderr:", result.stderr.replace(/\s+$/, ""));
+  }
+  if (!result.stdout.trim() && !result.stderr.trim()) {
+    sections.push("", "(no output)");
+  }
+  return sections.join("\n");
+}
+
+export function formatDirectory(
+  entries: ReadonlyArray<RemoteEntry>,
+  remotePath: string,
+): string {
+  if (entries.length === 0) {
+    return `${remotePath} is empty.`;
+  }
+
+  const lines = entries.map((entry) => {
+    const suffix = entry.type === "directory" ? "/" : entry.type === "symlink" ? "@" : "";
+    const size = entry.type === "directory" ? "" : ` ${formatBytes(entry.size)}`;
+    const date = entry.modified ? ` ${entry.modified.slice(0, 10)}` : "";
+    return `${entry.mode}${date}${size}  ${entry.name}${suffix}`;
+  });
+
+  return [`${remotePath} (${entries.length} entries):`, ...lines].join("\n");
+}
+
+export function formatTransfer(result: TransferResult, direction: "up" | "down"): string {
+  return direction === "up"
+    ? `Uploaded ${result.localPath} to ${result.remotePath} (${formatBytes(result.size)}).`
+    : `Downloaded ${result.remotePath} to ${result.localPath} (${formatBytes(result.size)}).`;
+}
+
+export function formatAuthorizeResult(result: AuthorizeResult): string {
+  const lines = [
+    result.installed
+      ? `Key installed on the remote host and recorded in profile "${result.profile}".`
+      : `The key was already in ${result.authorizedKeysPath}; profile "${result.profile}" now uses it.`,
+    "",
+    `Private key: ${result.keyPath}`,
+    `Public key:  ${result.publicKeyPath}`,
+    `Fingerprint: ${result.fingerprint}`,
+    "",
+    result.verified
+      ? "Verified: a fresh connection authenticated with the key alone, so no password is needed from now on."
+      : "Warning: the key was installed but a key-only login could not be verified. The password is still in the profile as a fallback.",
+  ];
+  return lines.join("\n");
+}

package/src/keys.ts

@@ -0,0 +1,191 @@
+/**
+ * SSH key generation, in process.
+ *
+ * `ssh-keygen` is not something to depend on: it is absent on plenty of
+ * Windows installs, and the whole point of the key bootstrap is that it works
+ * without the user preparing anything first. Node can generate and sign with
+ * ed25519; what it cannot do is write OpenSSH's key formats, so those are
+ * encoded here.
+ *
+ * The output is byte-for-byte what ssh-keygen produces for an unencrypted
+ * ed25519 key, so the result also works with the plain `ssh` command.
+ */
+
+import * as crypto from "node:crypto";
+
+const KEY_TYPE = "ssh-ed25519";
+const AUTH_MAGIC = Buffer.from("openssh-key-v1\0", "binary");
+
+// --- SSH wire primitives --------------------------------------------------
+
+/** An SSH "string": a 32-bit big-endian length followed by the bytes. */
+function sshString(value: Buffer | string): Buffer {
+  const bytes = Buffer.isBuffer(value) ? value : Buffer.from(value, "utf-8");
+  const length = Buffer.alloc(4);
+  length.writeUInt32BE(bytes.length, 0);
+  return Buffer.concat([length, bytes]);
+}
+
+function uint32(value: number): Buffer {
+  const buffer = Buffer.alloc(4);
+  buffer.writeUInt32BE(value >>> 0, 0);
+  return buffer;
+}
+
+/** Read an SSH string, returning it and the offset after it. */
+function readSshString(buffer: Buffer, offset: number): [Buffer, number] {
+  const length = buffer.readUInt32BE(offset);
+  const start = offset + 4;
+  return [buffer.subarray(start, start + length), start + length];
+}
+
+// --- Public keys ----------------------------------------------------------
+
+/** The wire-format blob for an ed25519 public key. */
+export function publicKeyBlob(publicKeyRaw: Buffer): Buffer {
+  return Buffer.concat([sshString(KEY_TYPE), sshString(publicKeyRaw)]);
+}
+
+/** One authorized_keys / .pub line: "ssh-ed25519 <base64> <comment>". */
+export function formatPublicKeyLine(publicKeyRaw: Buffer, comment: string): string {
+  const encoded = publicKeyBlob(publicKeyRaw).toString("base64");
+  const suffix = comment.trim() ? ` ${comment.trim()}` : "";
+  return `${KEY_TYPE} ${encoded}${suffix}`;
+}
+
+/** One line built from an already-encoded key blob, e.g. one ssh2 parsed. */
+export function formatPublicKeyLineFromBlob(blob: Buffer, comment: string): string {
+  const suffix = comment.trim() ? ` ${comment.trim()}` : "";
+  return `${keyBlobType(blob)} ${blob.toString("base64")}${suffix}`;
+}
+
+/**
+ * The fingerprint OpenSSH shows: SHA256 over the key blob, base64, unpadded.
+ */
+export function keyFingerprint(blob: Buffer): string {
+  const digest = crypto.createHash("sha256").update(blob).digest("base64");
+  return `SHA256:${digest.replace(/=+$/, "")}`;
+}
+
+/** Pull the algorithm name out of a wire-format key blob. */
+export function keyBlobType(blob: Buffer): string {
+  try {
+    const [type] = readSshString(blob, 0);
+    return type.toString("utf-8");
+  } catch {
+    return "unknown";
+  }
+}
+
+// --- Private keys ---------------------------------------------------------
+
+function toPem(body: Buffer): string {
+  const encoded = body.toString("base64").replace(/(.{70})/g, "$1\n").replace(/\n$/, "");
+  return `-----BEGIN OPENSSH PRIVATE KEY-----\n${encoded}\n-----END OPENSSH PRIVATE KEY-----\n`;
+}
+
+/**
+ * Encode an unencrypted ed25519 private key in OpenSSH's container format.
+ *
+ * The layout is: magic, cipher/kdf names (all "none" here), the public key,
+ * then a "private" section holding a repeated check integer, the key pair,
+ * the comment, and padding to the cipher block size.
+ */
+function encodeOpenSshPrivateKey(
+  publicKeyRaw: Buffer,
+  privateSeed: Buffer,
+  comment: string,
+): string {
+  const pubBlob = publicKeyBlob(publicKeyRaw);
+
+  // The two check integers must match; a wrong passphrase shows up as a
+  // mismatch when the section is encrypted. Unencrypted, they are a checksum.
+  const check = crypto.randomBytes(4);
+  const privateSection: Buffer[] = [
+    check,
+    check,
+    sshString(KEY_TYPE),
+    sshString(publicKeyRaw),
+    // OpenSSH stores seed and public key together as the 64-byte private key.
+    sshString(Buffer.concat([privateSeed, publicKeyRaw])),
+    sshString(comment),
+  ];
+
+  let body = Buffer.concat(privateSection);
+  // Pad to a multiple of 8 with 1, 2, 3, ... as OpenSSH does.
+  const blockSize = 8;
+  const padding: number[] = [];
+  for (let i = 1; (body.length + padding.length) % blockSize !== 0; i += 1) {
+    padding.push(i);
+  }
+  body = Buffer.concat([body, Buffer.from(padding)]);
+
+  return toPem(
+    Buffer.concat([
+      AUTH_MAGIC,
+      sshString("none"), // ciphername
+      sshString("none"), // kdfname
+      sshString(""), // kdfoptions
+      uint32(1), // number of keys
+      sshString(pubBlob),
+      sshString(body),
+    ]),
+  );
+}
+
+export interface GeneratedKeyPair {
+  /** OpenSSH private key, ready to write to a file or hand to ssh2. */
+  readonly privateKey: string;
+  /** One authorized_keys line. */
+  readonly publicKey: string;
+  readonly fingerprint: string;
+  readonly comment: string;
+}
+
+/**
+ * Generate an ed25519 key pair.
+ *
+ * ed25519 rather than RSA: every OpenSSH released in the last decade accepts
+ * it, the keys are short enough to paste, and generation is instant.
+ */
+export function generateKeyPair(comment: string): GeneratedKeyPair {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
+
+  // The JWK export is the only way to get the raw 32-byte values out of Node.
+  const publicJwk = publicKey.export({ format: "jwk" }) as { x: string };
+  const privateJwk = privateKey.export({ format: "jwk" }) as { d: string };
+
+  const publicRaw = Buffer.from(publicJwk.x, "base64url");
+  const seed = Buffer.from(privateJwk.d, "base64url");
+
+  if (publicRaw.length !== 32 || seed.length !== 32) {
+    throw new Error("Unexpected ed25519 key size from the crypto module.");
+  }
+
+  return {
+    privateKey: encodeOpenSshPrivateKey(publicRaw, seed, comment),
+    publicKey: formatPublicKeyLine(publicRaw, comment),
+    fingerprint: keyFingerprint(publicKeyBlob(publicRaw)),
+    comment,
+  };
+}
+
+/** A default comment identifying where the key was made. */
+export function defaultKeyComment(user: string, host: string): string {
+  return `pi-ssh ${user}@${host}`;
+}
+
+/**
+ * Compare two authorized_keys lines by their key material, ignoring the
+ * comment and any options prefix, so re-running the bootstrap does not append
+ * a second copy of the same key.
+ */
+export function sameKeyMaterial(a: string, b: string): boolean {
+  const material = (line: string) => {
+    const parts = line.trim().split(/\s+/);
+    const index = parts.findIndex((part) => /^(ssh|ecdsa|sk)-/.test(part));
+    return index === -1 ? "" : parts.slice(index, index + 2).join(" ");
+  };
+  const left = material(a);
+  return left.length > 0 && left === material(b);
+}