@tiphareth/dsh-hardssh 0.1.2 → 0.2.3

package/lib/types/ssh/connection/manager.d.ts

@@ -0,0 +1,359 @@
+import { Client, type ConnectConfig } from 'ssh2';
+import { type SshConnectionService } from './pool.ts';
+import { HostKeyPolicy, type HostKeyCheck, type KnownHostsStore } from '../known-hosts.ts';
+import type { ClusterResult, ExecResult, SshHostEntry, SshHostSummary, TestResult } from '../protocol.ts';
+import type { HostStoreView } from '../../core.ts';
+export interface SshInvalidateOptions {
+    /**
+     * Also invalidate hosts whose ProxyJump chain depends, directly or
+     * transitively, on the changed alias.
+     */
+    includeDependents?: boolean;
+    /**
+     * drain: reject/reconnect subsequent acquisitions, allow existing leases
+     * to complete before closing their transport.
+     * force: close the current transport immediately.
+     */
+    mode?: 'drain' | 'force';
+}
+/** Default engine knobs. */
+export interface EngineOptions {
+    /** Connections idle longer than this are closed (ms). */
+    idleTimeoutMs?: number;
+    /** SSH handshake timeout (ms). */
+    connectTimeoutMs?: number;
+    /** Keepalive ping interval (ms). */
+    keepaliveIntervalMs?: number;
+    /** Cap on captured stdout/stderr bytes per exec (ms). */
+    maxOutputBytes?: number;
+    /** Default exec timeout (ms). */
+    defaultExecTimeoutMs?: number;
+    /** Default cluster concurrency. */
+    defaultMaxWorkers?: number;
+    /** SFTP concurrent channel count for transfers. */
+    sftpConcurrency?: number;
+    /** Deadline for opening an SFTP subsystem channel. */
+    sftpOpenTimeoutMs?: number;
+    /** Per-request SFTP callback deadline. */
+    sftpOperationTimeoutMs?: number;
+    /** Whole-file read/write stream inactivity deadline. */
+    sftpReadTimeoutMs?: number;
+    /** Maximum bytes buffered by readFile before it aborts. */
+    maxReadFileBytes?: number;
+    /** Upload/download inactivity deadline, reset by progress. */
+    sftpTransferIdleTimeoutMs?: number;
+    /** Absolute budget for one recursive rm traversal. */
+    sftpRecursiveRmTimeoutMs?: number;
+    /**
+     * Optional server-host-key algorithm whitelist (e.g. ['ssh-ed25519']).
+     * Single authoritative source: connection building reads it from these
+     * options (EngineDeps deliberately has no duplicate).
+     */
+    hostKeyAlgorithms?: string[];
+}
+/**
+ * Optional engine dependencies for host-key TOFU and secret resolution.
+ * All fields are optional and their absence preserves the pre-security
+ * behavior exactly (plaintext inline auth, no host verification) — the
+ * existing tests and call sites keep working unchanged.
+ */
+export interface EngineDeps {
+    /** Known-hosts trust store; when set, connections require a trusted host key. */
+    knownHosts?: KnownHostsStore;
+    /** Fingerprint check policy (defaults to a HostKeyPolicy over knownHosts). */
+    hostKeyPolicy?: HostKeyPolicy;
+    /**
+     * Secret resolution for one entry. Absent: read `password`/`passphrase`
+     * inline from the entry (plaintext store / test compatibility).
+     */
+    resolveSecrets?: (entry: SshHostEntry) => Promise<ResolvedAuthDeps>;
+    /** Final output/error redactor (typically the unlocked credential vault). */
+    redactOutput?: (text: string) => string;
+}
+/** The resolved-auth shape passed into connect config building (vault-aware). */
+export interface ResolvedAuthDeps {
+    kind: SshHostEntry['auth']['kind'];
+    keyPath?: string;
+    password?: string;
+    passphrase?: string;
+}
+/**
+ * Thrown when a connection needs a password/passphrase that is not yet
+ * available in this session (secretStorage='none' and the user hasn't entered
+ * it yet). The GUI intercepts this and prompts for the credential, then
+ * injects it via engine.setSessionPassword and retries.
+ */
+export declare class NeedsPasswordError extends Error {
+    /** Which secret the connection needs: 'password' or 'passphrase'. */
+    readonly secret: 'password' | 'passphrase';
+    constructor(alias: string, secret: 'password' | 'passphrase');
+}
+export declare const DEFAULTS: Required<Omit<EngineOptions, 'hostKeyAlgorithms'>> & Pick<EngineOptions, 'hostKeyAlgorithms'>;
+/**
+ * How much an operation may be retried:
+ * - never: one acquisition + one operation attempt.
+ * - connect-only: connection acquisition may be retried, but once the
+ *   operation function starts it is invoked at most once (default).
+ * - idempotent: the operation may also be retried until it calls
+ *   markCommitted() (i.e. while the exec channel is still opening).
+ *
+ * SFTP operations must never use 'idempotent': they have no commit point, so
+ * a replay after a mid-flight timeout would duplicate a remote write.
+ */
+export type RetryPolicy = 'never' | 'connect-only' | 'idempotent';
+/** Options for a one-shot remote command. */
+export interface ExecOptions {
+    timeoutMs?: number;
+    retry?: RetryPolicy;
+    signal?: AbortSignal;
+}
+/** Internal options for withClient(). */
+export interface WithClientOptions {
+    /** Total acquire+operation attempt budget (default 3, capped at 1 for 'never'). */
+    attempts?: number;
+    retryPolicy?: RetryPolicy;
+    signal?: AbortSignal;
+}
+/** Lets an operation declare the point after which replay is unsafe. */
+export interface OperationControl {
+    markCommitted(): void;
+    /**
+     * The caller's abort signal for THIS operation (undefined = not cancellable).
+     * Operations that can cancel their own request (`exec` closing its channel,
+     * an SFTP read stream) listen here, so an abort does not have to retire the
+     * whole shared transport out from under concurrent holders.
+     */
+    readonly signal?: AbortSignal;
+}
+export interface HostKeyOutcome {
+    alias: string;
+    check: HostKeyCheck;
+}
+/**
+ * Half-open channels tolerated on one pooled transport before it is retired.
+ * Deliberately well below OpenSSH's default `MaxSessions` (10) so the budget is
+ * never actually exhausted.
+ */
+export declare const MAX_LEAKED_CHANNELS = 4;
+/**
+ * Resolve the ssh-agent socket to offer to ssh2 (zero-input key auth,
+ * VSCode-style): `$SSH_AUTH_SOCK` — the standard OpenSSH agent socket (also
+ * exported by Git for Windows' ssh-agent and WSL). Deliberately NOT probing
+ * named pipes (Pageant / Windows OpenSSH agent): an absent pipe makes ssh2's
+ * agent query stall the whole handshake until readyTimeout instead of
+ * falling through to the next method. Keep Pageant compatibility for a
+ * future explicit opt-in. An agent that yields no keys makes ssh2 fall
+ * through to the configured methods (privateKey → password), so enabling it
+ * when a socket is present is safe. Exported for tests.
+ */
+export declare function sshAgentConfig(): string | undefined;
+/** Build the ssh2 connect config for one entry (key read from disk). The
+ *  timeout/keepalive knobs come from EngineOptions so they actually take
+ *  effect instead of being hard-coded. Exported for tests. */
+export declare function buildConnectConfig(entry: SshHostEntry, options: Pick<Required<EngineOptions>, 'connectTimeoutMs' | 'keepaliveIntervalMs'>, sock?: ConnectConfig['sock'], buildContext?: {
+    hostKeyPolicy?: HostKeyPolicy;
+    hostKeyAlgorithms?: string[];
+    /** Writes the verified/refused outcome back to the caller's capture slot. */
+    setOutcome?: (value: HostKeyOutcome) => void;
+    /** Vault-resolved authentication (overrides entry.auth secrets). */
+    authOverride?: ResolvedAuthDeps;
+}): ConnectConfig;
+/**
+ * Host-side hooks the connection manager needs but must not own. Injected by
+ * the facade so every resource keeps exactly one dispose point and the manager
+ * never imports the facade back (no cycle).
+ */
+export interface ConnectionManagerAccess {
+    /** A pooled client is being torn down — drop its cached SFTP channel. */
+    onClientDisposed?(client: Client, error: Error): void;
+    /** Vault-aware output guard applied before session-secret masking. */
+    redactOutput?(text: string): string;
+    /**
+     * The one-command runner (the facade's `exec`). Injected rather than
+     * reimplemented here so cluster() fans out through the SAME method surface
+     * callers/spies observe on the engine, and `test` reuses it verbatim.
+     */
+    executor?: (alias: string, command: string, options?: ExecOptions) => Promise<ExecResult>;
+}
+/**
+ * Owns the pooled SSH connections and everything layered on them: per-alias
+ * ProxyJump connect chains, session-scoped secrets and output redaction, the
+ * retry/replay policy, and the command surface (exec/cluster/test).
+ *
+ * Dispose order lives in the facade: tunnels, standalone terminal transports
+ * and SFTP channels are closed first, so a resource is always closed before
+ * the transport that carries it.
+ */
+export declare class ConnectionManager {
+    private readonly store;
+    private readonly opts;
+    private readonly access;
+    private readonly executor;
+    private readonly connectionPool;
+    private readonly deps;
+    private readonly hostKeyPolicy;
+    /**
+     * Session-scoped secrets (secretStorage='none'): keyed by alias, populated
+     * by the GUI on first connect, used by connectChain's resolve step, and
+     * cleared on dispose. Never persisted.
+     */
+    private readonly sessionPasswords;
+    /**
+     * alias → every secret value registered for it in this process, including
+     * ones replaced by a newer value. Released with the alias's connection, so a
+     * rotated password stays redacted while the old connection can still echo it.
+     */
+    private readonly secretHistory;
+    private readonly sensitiveOutputs;
+    /** Per-alias count of channels that never acknowledged close after a timeout. */
+    private readonly leakedChannels;
+    /**
+     * @param store - the host config store.
+     * @param options - engine knobs (defaults applied after validation).
+     * @param deps - optional security deps (host-key TOFU, secret resolution).
+     *   Absent → pre-security behavior (inline auth, no host verification).
+     * @param access - optional host-side hooks (SFTP cache eviction, redactor).
+     */
+    constructor(store: HostStoreView, options?: EngineOptions, deps?: EngineDeps, access?: ConnectionManagerAccess);
+    /** Validate the engine knobs once, so the connection and SFTP components
+     *  read one frozen source of truth. */
+    static resolveOptions(options?: EngineOptions): Required<Omit<EngineOptions, 'hostKeyAlgorithms'>> & Pick<EngineOptions, 'hostKeyAlgorithms'>;
+    /** Aliases with a live pooled transport right now (for connection-state
+     *  indicators — the GUI badge colors bound workspaces by it). */
+    connectedAliases(): string[];
+    /**
+     * Record one channel that never acknowledged its close after a hard timeout.
+     *
+     * ssh2 cannot cancel a request, so a peer that ignores KILL + close leaves a
+     * half-open channel counted against the server's `MaxSessions` budget. Once
+     * enough of them accumulate the pooled transport is DRAINED — not force-
+     * closed — so concurrent holders finish their work while new operations open
+     * a fresh generation (the pool reaps the old record when its last lease is
+     * released).
+     *
+     * The counter is per alias and is decremented again by
+     * {@link noteChannelClosed} when a late acknowledgement finally arrives, so a
+     * merely slow peer cannot accumulate its way to a retirement.
+     *
+     * @param alias - the host the channel belonged to.
+     * @returns true when the transport was retired.
+     */
+    noteLeakedChannel(alias: string): boolean;
+    /** A timed-out channel finally acknowledged its close: un-count it. */
+    noteChannelClosed(alias: string): void;
+    /** Pooled connections owned by this manager (the tunnel component's narrow
+     *  access seam, and the public `connections` getter on the facade). */
+    get connections(): SshConnectionService;
+    /** The validated engine knobs. The facade's exec reads its output cap and
+     *  default budget here, so defaults keep exactly one source of truth. */
+    get resolvedOptions(): Required<Omit<EngineOptions, 'hostKeyAlgorithms'>> & Pick<EngineOptions, 'hostKeyAlgorithms'>;
+    /**
+     * Provide a secret for `alias` for THIS session only (never persisted).
+     * Used by the GUI when a connection needs a password/passphrase under
+     * secretStorage='none'. Once set, pooled connections reuse it until the
+     * session ends or clearSessionSecrets() is called.
+     */
+    setSessionPassword(alias: string, secret: {
+        password?: string;
+        passphrase?: string;
+    }): void;
+    /** Read the session secret for one alias (undefined = not provided yet). */
+    getSessionPassword(alias: string): {
+        password?: string;
+        passphrase?: string;
+    } | undefined;
+    /**
+     * Drop ONE alias's session secret. Called when its pooled connection is
+     * retired: the credential is tied to the connection's lifetime, so an idle
+     * sweep must not leave it usable for the rest of the process.
+     */
+    forgetSessionPassword(alias: string): void;
+    /** Drop every session secret (e.g. on secretStorage change / lock). */
+    clearSessionSecrets(): void;
+    /** Recompute the redaction set from every secret still in force, including
+     *  values replaced by a newer one on the same alias (their connection may
+     *  still be alive), so dropping one alias never un-redacts another's. */
+    private rebuildSensitiveOutputs;
+    /** Redact credentials known to this session and the optional vault guard. */
+    redact(text: string): string;
+    /** Secret-free host list (filtered by the optional query). */
+    list(query?: string): SshHostSummary[];
+    /** One host summary by alias. */
+    find(alias: string): SshHostSummary | undefined;
+    /**
+     * Retire the pooled connection for one alias.
+     *
+     * ConnectionPool knows nothing about HostStore or ProxyJump configuration
+     * (every target owns its complete jump chain, no hop records are shared),
+     * so dependent-host expansion belongs here: with includeDependents the
+     * transitive reverse ProxyJump closure of `alias` is invalidated too.
+     */
+    invalidate(alias: string, options?: SshInvalidateOptions): void;
+    /**
+     * Run `fn` with a live client for `alias`.
+     *
+     * Acquisition retry and operation replay are deliberately separate:
+     * - never: one acquire + one operation attempt.
+     * - connect-only: acquire may be retried, but fn is invoked at most once —
+     *   once fn starts, the remote may already have observed the request, so
+     *   replay could duplicate non-idempotent work.
+     * - idempotent: fn may be retried until it calls control.markCommitted()
+     *   (exec marks this when the server accepted the channel).
+     *
+     * A failed operation retires the transport via lease.markBroken(); the
+     * lease is always released before the next acquire attempt.
+     */
+    withClient<T>(alias: string, fn: (client: Client, control: OperationControl) => Promise<T>, options?: WithClientOptions): Promise<T>;
+    /** Resolve an entry's authentication for one connect: session password
+     *  table first (secretStorage='none'), then deps.resolveSecrets (vault),
+     *  then the inline store entry; when a password/passphrase is required but
+     *  unavailable, throw NeedsPasswordError for the GUI to prompt. */
+    resolveEntryAuth(entry: SshHostEntry): Promise<ResolvedAuthDeps | undefined>;
+    /**
+     * Build one full jump chain for an entry: hop clients connected through in
+     * order, each forwarding a stream to the next destination, ending with the
+     * target client. Shared by the pool and standalone shell sessions.
+     */
+    connectChain(entry: SshHostEntry, signal?: AbortSignal): Promise<{
+        client: Client;
+        hops: Client[];
+    }>;
+    /**
+     * Run one command against many hosts concurrently.
+     *
+     * Per-host failures carry the typed, secret-free fields declared on
+     * `ClusterResult` (`code`, and `secret` / `hostKeyFingerprint` / `expected` /
+     * `actual` where applicable) alongside the legacy `error` string, so
+     * automation can branch on a stable code and the GUI can open the right
+     * credential/fingerprint dialog without parsing a localized message.
+     */
+    cluster(options: {
+        command: string;
+        aliases?: string[];
+        environment?: string;
+        tags?: string[];
+        timeoutMs?: number;
+        maxWorkers?: number;
+        /** Aborts every per-host run when the caller disconnects. */
+        signal?: AbortSignal;
+    }): Promise<ClusterResult[]>;
+    /**
+     * Classify one per-host cluster failure. Keeps the legacy `error` string for
+     * backward compatibility while adding the typed reason: a NeedsPassword /
+     * host-key failure is interactive in the GUI, and automation needs a stable
+     * code. The message is redacted because connect/resolve errors can embed a
+     * credential; the added fields are fingerprints and enum values only.
+     */
+    clusterFailure(alias: string, error: unknown): ClusterResult;
+    /** Probe connectivity: connect, run `true`, close. Typed errors the GUI
+     *  must react to (host-key TOFU, session password) are NOT flattened into
+     *  a plain message — callers (routes → panel / workspace gate) key their
+     *  interactive dialogs on the typed error. Everything else (unreachable,
+     *  timeout, auth failure) returns a failed result. */
+    test(alias: string, signal?: AbortSignal): Promise<TestResult>;
+    /** Close every pooled connection and wipe the in-memory session password
+     *  table. The facade calls this LAST, after tunnels, terminal transports and
+     *  SFTP channels are already closed (secrets are never persisted anywhere). */
+    disposeSensitive(): void;
+}
+//# sourceMappingURL=manager.d.ts.map

package/lib/types/ssh/connection/pool.d.ts

@@ -18,12 +18,19 @@ export interface SshConnectionService {
 export interface ConnectionPoolOptions {
     idleTimeoutMs: number;
     /** Open a fresh SSH connection (with jump chain) for one alias. */
-    connect(alias: string): Promise<{
+    connect(alias: string, signal?: AbortSignal): Promise<{
         client: Client;
         hops: Client[];
     }>;
     /** Called when a pooled connection is torn down (e.g. drop SFTP cache). */
     onDispose?(client: Client): void;
+    /**
+     * Called once when an alias's pooled transport is retired (idle sweep,
+     * invalidation, shutdown). Session-scoped credentials are tied to the pooled
+     * connection's lifetime, so this is where they are dropped — otherwise a
+     * secret entered for one connection would outlive it for the whole process.
+     */
+    onRetire?(alias: string): void;
 }
 /**
  * Per-alias connection pool with explicit leases. A connection is swept only