@xynogen/pix-ssh 0.5.9 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-ssh",
-	"version": "0.5.9",
+	"version": "0.6.1",
 	"description": "Pi tool \u2014 ssh_run: run remote commands over SSH with password/key auth and remote sudo",
 	"type": "module",
 	"main": "src/index.ts",

package/src/index.ts

@@ -16,7 +16,8 @@
  *
  * Connection reuse: OpenSSH ControlMaster multiplexing keeps one authenticated
  * connection per host alive (ControlPersist window), so repeat calls skip
- * re-auth.
+ * re-auth. `fresh: true` stops that master first, and every result reports the
+ * auth method (key/password) and whether the connection was new or reused.
  *
  * Security notes:
  *   - Passwords never leave JS memory; never written to disk; never in argv.
@@ -25,12 +26,17 @@
  *   - Output truncated to 50 KB / 2000 lines.
  */
 
+import { existsSync } from "node:fs";
 import type { AgentToolUpdateCallback, ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { resolveBaseBackground } from "@xynogen/pix-pretty/ansi";
 import { collapsedCommandRow, commandPreview } from "@xynogen/pix-pretty/command-preview";
 import { MAX_PREVIEW_LINES } from "@xynogen/pix-pretty/config";
-import { type OverlayResult, showOverlay } from "@xynogen/pix-pretty/gate-overlay";
+import {
+	type OverlayChoice,
+	type OverlayResult,
+	showOverlay,
+} from "@xynogen/pix-pretty/gate-overlay";
 import { icon } from "@xynogen/pix-pretty/icon-catalog";
 import { renderBashOutput } from "@xynogen/pix-pretty/renderers";
 import type { RenderContextLike, ThemeLike, ToolResultLike } from "@xynogen/pix-pretty/types";
@@ -59,6 +65,7 @@ import { type CollapseState, tickCollapse } from "@xynogen/pix-runtime/collapse"
 import { Type } from "typebox";
 import {
 	APPROVAL_TTL_MS,
+	closeMaster,
 	commandEscalatesPrivilege,
 	controlPathFor,
 	detectSshFailure,
@@ -87,6 +94,9 @@ import {
 const PROMPT_TIMEOUT_MS = 60_000;
 const MAX_PASSWORD_ATTEMPTS = 3;
 const SPINNER_INTERVAL_MS = 120;
+/** Min gap between key re-checks on a host whose login password is cached.
+ * Each failed probe is one auth failure in the server log (fail2ban counts it). */
+const KEY_RECHECK_MS = 60_000;
 
 // In-memory per-host credential cache (session-scoped, never persisted).
 // Key = canonical "user@host:port". Cleared on process exit.
@@ -95,6 +105,8 @@ interface HostCreds {
 	sudoPassword?: string;
 }
 const credCache = new Map<string, HostCreds>();
+// Per-host epoch ms before which the cached-password key re-check is skipped.
+const keyRecheckAt = new Map<string, number>();
 
 // Per-host allow-memory (on by default): once the user approves any command on
 // a host, later calls to that host skip the confirm overlay until the approval
@@ -108,6 +120,53 @@ function cacheKey(spec: HostSpec): string {
 	return `${spec.user ?? ""}@${spec.host}:${spec.port ?? 22}`;
 }
 
+/** Pre-run connection prep: honor `fresh`, re-check the key, and report
+ * whether the run will reuse a live master. Checked before the auth probes,
+ * which open a master themselves. */
+async function prepareConnection(
+	spec: HostSpec,
+	controlPath: string,
+	key: string,
+	creds: HostCreds,
+	fresh: boolean | undefined,
+	sig?: AbortSignal,
+): Promise<{ creds: HostCreds; connection: "new" | "reused" }> {
+	if (fresh === true) await closeMaster(spec, controlPath, sig);
+	const next = await recheckKey(spec, controlPath, key, creds, fresh === true, sig);
+	return { creds: next, connection: existsSync(controlPath) ? "reused" : "new" };
+}
+
+function authVia(loginPassword: string | undefined, connection: "new" | "reused") {
+	return { auth: loginPassword ? "password" : "key", connection } as const;
+}
+
+/**
+ * A cached login password means the live master is likely password-authed, so a
+ * normal probe would ride it and never test the key. Re-check the key with
+ * multiplexing off (rate-limited by KEY_RECHECK_MS unless `force`); on success
+ * drop the password and its master so this call and later ones use the key.
+ */
+async function recheckKey(
+	spec: HostSpec,
+	controlPath: string,
+	key: string,
+	creds: HostCreds,
+	force: boolean,
+	sig?: AbortSignal,
+): Promise<HostCreds> {
+	if (!creds.loginPassword) return creds;
+	if (!force && (keyRecheckAt.get(key) ?? 0) > Date.now()) return creds;
+	if ((await probeKeyAuth(spec, "none", sig)) !== "ok") {
+		keyRecheckAt.set(key, Date.now() + KEY_RECHECK_MS);
+		return creds;
+	}
+	const next = creds.sudoPassword ? { sudoPassword: creds.sudoPassword } : {};
+	credCache.set(key, next);
+	keyRecheckAt.delete(key);
+	await closeMaster(spec, controlPath, sig);
+	return next;
+}
+
 /**
  * Overlay password validator for a prompt stage. The login stage tests the
  * password against the host (wrong one re-prompts up to MAX_PASSWORD_ATTEMPTS);
@@ -149,6 +208,10 @@ export interface SshResultDetails {
 	truncated?: boolean;
 	cancellationKind?: SshCancellationKind;
 	errorKind?: SshErrorKind;
+	/** How this call authenticated: SSH key/agent, or a login password. */
+	auth?: "key" | "password";
+	/** Whether this call opened a new connection or reused a live master. */
+	connection?: "new" | "reused";
 	_render?: string;
 }
 
@@ -164,6 +227,7 @@ type SshParams = {
 	destination?: string;
 	recursive?: boolean;
 	reason?: string;
+	fresh?: boolean;
 };
 
 interface SshOperation {
@@ -203,10 +267,17 @@ function normalizeOperation(params: SshParams): SshOperation {
 	};
 }
 
+/** The model's reason heads the modal; the action name is only the fallback. */
+function approvalTitle({ action, direction, reason }: SshOperation): string {
+	if (reason?.trim()) return reason.trim();
+	if (action !== "file") return "SSH Command Request";
+	return `SSH ${direction === "download" ? "Download" : "Upload"}`;
+}
+
 function approvalBody(operation: SshOperation, host: string, port?: number): string[] {
 	const { action, command, destination, direction, reason, recursive, source, sudo } = operation;
 	return [
-		reason?.trim() ? `Intent: ${reason.trim()}` : "No reason provided by AI",
+		...(reason?.trim() ? [] : ["No reason provided by AI"]),
 		`Host: ${host}${port ? ` (port ${port})` : ""}`,
 		...(action === "command"
 			? [`Command: ${sudo ? "sudo " : ""}${command}`]
@@ -283,6 +354,8 @@ function terminalMeta(details: SshResultDetails): string {
 	const hasLines = typeof details.lineCount === "number" && details.lineCount > 0;
 	return dotJoin([
 		typeof details.exitCode === "number" && `exit ${details.exitCode}`,
+		details.auth && `${details.auth} auth`,
+		details.connection && `${details.connection} connection`,
 		hasLines && `${details.lineCount} ${details.lineCount === 1 ? "line" : "lines"}`,
 		details.truncated && "truncated",
 	]);
@@ -398,7 +471,16 @@ async function infoResult(host: string | undefined, sig?: AbortSignal) {
 
 // ── Extension entry point ─────────────────────────────────────────────────────
 
+/** "Allow for this session" choice. Offered only for non-privileged commands. */
+const SESSION_CHOICE: OverlayChoice[] = [
+	{ value: "session", label: "Allow for this session", description: "Host, until /new; sudo asks" },
+];
+
 export default function (pi: ExtensionAPI): void {
+	// "Allow for this session" hosts. Lives in the factory: Pi hands each new session a fresh `pi`,
+	// so this resets on /new. Privileged commands never use it (see `privileged` below).
+	const sessionHosts = new Set<string>();
+	const approved = (key: string) => sessionHosts.has(key) || hostApproved(approvedHosts, key);
 	pi.registerTool({
 		name: "ssh_run",
 		...({ exposure: "deferred" } as const),
@@ -465,11 +547,15 @@ export default function (pi: ExtensionAPI): void {
 					description: "[file] Optional, default false. Copy a directory recursively.",
 				}),
 			),
-			reason: Type.Optional(
-				Type.String({
-					description: "All actions. Short plain-English intent, shown to the user.",
+			fresh: Type.Optional(
+				Type.Boolean({
+					description:
+						"[command|file] Optional, default false. Close the reused connection first so this call re-authenticates (e.g. to prove key login).",
 				}),
 			),
+			reason: Type.String({
+				description: "Short plain-English intent, shown to the user as the approval title.",
+			}),
 		}),
 
 		async execute(_toolCallId, params, sig, onUpdate, ctx) {
@@ -550,7 +636,7 @@ export default function (pi: ExtensionAPI): void {
 			// ProxyJump, and other SSH config options still apply.
 			const controlPath = controlPathFor(effectiveSpec);
 			const key = cacheKey(effectiveSpec);
-			const creds = credCache.get(key) ?? {};
+			let creds = credCache.get(key) ?? {};
 
 			const mode = getUnattendedMode(pi.events);
 			const yolo = mode === "yolo";
@@ -579,6 +665,10 @@ export default function (pi: ExtensionAPI): void {
 
 			updatePresentation(onUpdate, command, host, sudo, reason, "awaiting-approval");
 
+			const prep = await prepareConnection(spec, controlPath, key, creds, params.fresh, sig);
+			creds = prep.creds;
+			const connection = prep.connection;
+
 			// Probe key/agent/existing-master auth (no password needed on success).
 			// Only prompt for a login password when the host is reachable but rejects
 			// key auth ("auth"). If it's unreachable (timeout/DNS/refused) a password
@@ -619,6 +709,7 @@ export default function (pi: ExtensionAPI): void {
 				};
 			}
 
+			const title = approvalTitle(operation);
 			const body = [
 				...approvalBody(operation, host, spec.port),
 				...(keyOk && !creds.loginPassword ? ["Auth: SSH key (no password)"] : []),
@@ -636,10 +727,7 @@ export default function (pi: ExtensionAPI): void {
 			// auto-approved — they always re-confirm.
 			const privileged = action === "command" && (sudo || commandEscalatesPrivilege(command));
 			const alreadyApproved =
-				action === "command" &&
-				!privileged &&
-				hostApproved(approvedHosts, key) &&
-				promptFor.length === 0;
+				action === "command" && !privileged && approved(key) && promptFor.length === 0;
 			if (alreadyApproved) {
 				ctx.ui.notify(`ssh_run: reused session approval for ${host}`, "info");
 			} else if (transferDecision === "allow") {
@@ -649,6 +737,8 @@ export default function (pi: ExtensionAPI): void {
 				);
 			}
 
+			const sessionChoices = action === "command" && !privileged ? SESSION_CHOICE : [];
+
 			const runOverlay = (): Promise<OverlayResult> =>
 				withAgentBlock(pi.events, "ssh_run", "SSH approval required", async () => {
 					if ((transferDecision === "allow" || yolo || alreadyApproved) && promptFor.length === 0) {
@@ -659,13 +749,11 @@ export default function (pi: ExtensionAPI): void {
 						return showOverlay(ctx.ui, {
 							mode: "confirm",
 							icon: action === "file" ? icon("warn") : icon("lock"),
-							title:
-								action === "file"
-									? `SSH ${direction === "download" ? "Download" : "Upload"}`
-									: "SSH Command Request",
+							title,
 							body,
 							accent: sudo ? "error" : action === "file" ? "warning" : "accent",
 							timeoutMs: PROMPT_TIMEOUT_MS,
+							approveValue: ["yes", "session"],
 							choices: [
 								{
 									value: "yes",
@@ -673,6 +761,7 @@ export default function (pi: ExtensionAPI): void {
 									description:
 										action === "file" ? "Copy to destination (may overwrite)" : "Run the command",
 								},
+								...sessionChoices,
 								{
 									value: "no",
 									label: "Deny",
@@ -688,14 +777,12 @@ export default function (pi: ExtensionAPI): void {
 						last = await showOverlay(ctx.ui, {
 							mode: "sudo",
 							icon: action === "file" ? icon("warn") : icon("lock"),
-							title:
-								action === "file"
-									? `SSH ${direction === "download" ? "Download" : "Upload"}`
-									: "SSH Command Request",
+							title,
 							body: [...body, `Enter: ${label}`],
 							accent: sudo ? "error" : action === "file" ? "warning" : "accent",
 							timeoutMs: PROMPT_TIMEOUT_MS,
 							maxPasswordAttempts: MAX_PASSWORD_ATTEMPTS,
+							approveValue: ["yes", "session"],
 							passwordLabel: `${label}:`,
 							// Login stage: actually test the password against the host so a
 							// wrong one re-prompts (up to MAX_PASSWORD_ATTEMPTS), mirroring
@@ -708,6 +795,7 @@ export default function (pi: ExtensionAPI): void {
 									label: "Allow",
 									description: `Enter ${label.toLowerCase()}`,
 								},
+								...sessionChoices,
 								{ value: "no", label: "Deny", description: "Block the command" },
 							],
 						});
@@ -731,9 +819,15 @@ export default function (pi: ExtensionAPI): void {
 			// File transfers remain warning-level: normal mode asks every time,
 			// AFK denies above, and YOLO may approve when no password is missing.
 			if (action === "command") approvedHosts.set(key, Date.now() + APPROVAL_TTL_MS);
+			// "session" is only offered for non-privileged commands (sessionChoices).
+			if (overlayResult.choice === "session") {
+				sessionHosts.add(key);
+				ctx.ui.notify(`ssh_run: ${host} allowed for this session (sudo still asks)`, "info");
+			}
 
 			// Persist newly-entered passwords in the session cache.
 			const loginPassword = creds.loginPassword ?? collected.login;
+			const via = authVia(loginPassword, connection);
 			const sudoPassword = creds.sudoPassword ?? collected.sudo;
 			credCache.set(key, {
 				...(loginPassword ? { loginPassword } : {}),
@@ -838,6 +932,7 @@ export default function (pi: ExtensionAPI): void {
 					details: makeDetails(command, host, sudo, reason, {
 						outcome: "error",
 						exitCode: result.code,
+						...via,
 						lineCount: outputLineCount(result.stderr),
 						errorKind: "auth-sudo",
 						_render: normalizeLineEndings(result.stderr),
@@ -856,10 +951,16 @@ export default function (pi: ExtensionAPI): void {
 				.replace(/^\n+|\n+$/g, "");
 
 			return {
-				content: [{ type: "text", text: `Exit code: ${result.code}\n\n${truncatedText}${suffix}` }],
+				content: [
+					{
+						type: "text",
+						text: `Exit code: ${result.code} (auth: ${via.auth}, ${via.connection} connection)\n\n${truncatedText}${suffix}`,
+					},
+				],
 				details: makeDetails(command, host, sudo, reason, {
 					outcome: result.code === 0 ? "success" : "error",
 					exitCode: result.code,
+					...via,
 					lineCount: outputLineCount(rendered),
 					truncated,
 					...(result.code === 0 ? {} : { errorKind: "exit-code" as const }),

package/src/lib.ts

@@ -431,6 +431,8 @@ export type ProbeResult = "ok" | "auth" | "unreachable";
  * clean connect (ok), auth rejected but host reachable (auth), and
  * connection/DNS failure (unreachable) — the last must NOT trigger a password
  * prompt, since a login password can't fix an unreachable host.
+ * Pass `controlPath = "none"` to bypass a live master: a password-authed master
+ * answers `ok` for any probe, which hides whether the key itself works.
  */
 export function probeKeyAuth(
 	spec: HostSpec,
@@ -454,6 +456,27 @@ export function probeKeyAuth(
 	});
 }
 
+/** argv that asks the live master on `controlPath` to stop accepting new
+ * sessions. `stop` (not `exit`) lets in-flight sessions finish. */
+export function closeMasterArgs(spec: HostSpec, controlPath: string): string[] {
+	return ["-o", `ControlPath=${controlPath}`, "-O", "stop", hostTarget(spec)];
+}
+
+/** Stop the multiplexed master so the next call opens (and authenticates) a
+ * fresh connection. No master = no-op; errors are ignored for the same reason. */
+export function closeMaster(
+	spec: HostSpec,
+	controlPath: string,
+	signal?: AbortSignal,
+): Promise<void> {
+	return new Promise((resolve) => {
+		const proc = spawnTool("ssh", closeMasterArgs(spec, controlPath), { stdio: "ignore" });
+		proc.on("error", () => resolve());
+		proc.on("close", () => resolve());
+		signal?.addEventListener("abort", () => proc.kill("SIGTERM"), { once: true });
+	});
+}
+
 /**
  * Validate an SSH *login* password by attempting one real password auth. Forces
  * password auth (no pubkey/agent) with a single prompt, fed via `sshpass -e`