@tiphareth/dsh-hardssh 0.1.2-alpha → 0.2.2

package/lib/types/ssh/engine.d.ts

@@ -1,101 +1,50 @@
 /**
- * The SSH engine: a per-alias persistent connection pool (ssh2) with
+ * The SSH engine facade: a per-alias persistent connection pool (ssh2) with
  * multi-hop jump support, command execution, PTY shells, SFTP transfers,
  * local port-forward tunnels and cluster execution —the DSH counterpart of
  * ssh-skill's daemon + scripts, living entirely in the host process.
+ *
+ * This module stays the public entry point (its export surface and the
+ * SshEngine class identity are load-bearing: production keys caches on the
+ * engine object in a WeakMap). The implementation lives in focused internal
+ * components, each owning one resource family:
+ *
+ *   connection/manager.ts  pooled connections, connect chains, secrets,
+ *                          retry/replay policy, exec/cluster/test, redaction
+ *   sftp/service.ts        SFTP subsystem channel cache + every SFTP operation
+ *   terminal/service.ts    standalone PTY shell / streaming exec transports
+ *   tunnel/service.ts      local listeners, forwarded sockets, tunnel leases
+ *
+ * Dependency direction is one-way (sftp/terminal/tunnel → connection); no
+ * component imports this facade back, so there is no cycle.
  */
-import { type ConnectConfig } from 'ssh2';
-import { type SshConnectionService } from './connection/pool.ts';
-import type { ClusterResult, ExecResult, SshHostEntry, SshHostSummary, TestResult, TransferProgress, TunnelInfo } from './protocol.ts';
+import type { Writable } from 'node:stream';
+import type { SshConnectionService } from './connection/pool.ts';
+import { type EngineDeps, type EngineOptions, type ExecOptions, type SshInvalidateOptions } from './connection/manager.ts';
+import type { SshHostSummary, TransferProgress, TunnelInfo } from './protocol.ts';
 import type { HostStoreView } from '../core.ts';
-import { HostKeyPolicy, type HostKeyCheck, type KnownHostsStore } from './known-hosts.ts';
-/** Options used when retiring pooled connections after host configuration changes. */
-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;
-    /** Optional server-host-key algorithm whitelist (e.g. ['ssh-ed25519']). */
-    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>;
-    /** Optional server-host-key algorithm whitelist override. */
-    hostKeyAlgorithms?: 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');
-}
 /**
- * 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).
+ * Enforce an exec budget ON THE SERVER as well as in the client.
  *
- * SFTP operations must never use 'idempotent': they have no commit point, so
- * a replay after a mid-flight timeout would duplicate a remote write.
+ * The client-side deadline only stops WAITING: measured against a real host
+ * (a CentOS 7 host running OpenSSH 7.4), a timed-out exec left BOTH the wrapper
+ * shell and its child running — `bash -c sleep 30` plus `sleep 30` were still
+ * alive 20s later — because ssh2's channel `signal` request was not delivered
+ * to the remote process, and closing the channel does not kill it either.
+ * Wrapping the command in coreutils `timeout` moves the deadline INSIDE the
+ * session, which does reap the whole process group (verified on the same host:
+ * exit 124 within the budget, zero orphans).
+ *
+ * The wrapper degrades to running the command verbatim when the server has no
+ * `timeout` (busybox or a minimal image), so no host becomes unusable.
+ *
+ * @param command - the caller's command, run unchanged inside the wrapper.
+ * @param budgetMs - the client-side budget this mirrors.
+ * @returns the command to hand to the remote shell.
  */
-export type RetryPolicy = 'never' | 'connect-only' | 'idempotent';
-/** Options for a one-shot remote command. */
-export interface ExecOptions {
-    timeoutMs?: number;
-    retry?: RetryPolicy;
-}
+export declare function wrapCommandWithServerBudget(command: string, budgetMs: number): string;
+export { buildConnectConfig, DEFAULTS, NeedsPasswordError, sshAgentConfig, } from './connection/manager.ts';
+export type { ConnectionManager, EngineDeps, EngineOptions, ExecOptions, ResolvedAuthDeps, RetryPolicy, SshInvalidateOptions, } from './connection/manager.ts';
 /** A live PTY shell session. */
 export interface ShellSession {
     /** Assign to receive remote output. */
@@ -121,82 +70,37 @@ export interface ShellSession {
  * input burst. Used by the subprocess capability seam's remote provider.
  */
 export interface ExecSession extends ShellSession {
+    /** Native ssh2 channel input. Using its real Writable contract preserves
+     * bytes, backpressure, errors and finish semantics for subprocess stdin. */
+    readonly stdin: Writable;
     /** Assign to receive the remote stderr stream. */
     onErrData?: (data: Buffer) => void;
     /** Send an SSH signal (e.g. 'TERM', 'KILL') to the remote process. */
     signal(name: string): void;
-    /** Write the final input burst and half-close stdin. */
+    /** Compatibility half-close for non-streaming callers. */
     end(data?: string): void;
 }
-/** One host-key verification outcome captured during a connect attempt (used
- *  to rewrite the generic handshake failure into a typed host-key error). */
-interface HostKeyOutcome {
-    alias: string;
-    check: HostKeyCheck;
-}
-/**
- * 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;
 /**
- * The engine. Owns the pool, tunnels, and all operations. One instance per
- * plugin apply; dispose() closes every connection.
+ * The SSH engine. Owns the connection pool, tunnels, standalone terminal
+ * transports and SFTP channels. One instance per plugin apply.
+ *
+ * Kept as the public facade over ConnectionManager/TunnelService/
+ * TerminalService/SftpService: every method here is a thin delegation, so the
+ * class identity (and therefore WeakMap cache keys in production) is stable.
  */
 export declare class SshEngine {
-    private readonly store;
-    private readonly opts;
-    private readonly tunnels;
-    /**
-     * One cached SFTP subsystem channel per live client. `Client.sftp()` opens a
-     * NEW subsystem channel on every call and OpenSSH caps open sessions per
-     * connection (MaxSessions, default 10) —reopening SFTP per operation lets
-     * channels pile up on the pooled long-lived connection until listing/reading
-     * fails intermittently. Caching one channel per client fixes that; the pool
-     * drops the cache via onDispose when a connection is torn down.
-     */
-    private readonly sftpChannels;
-    private readonly connectionPool;
-    private readonly deps;
-    private readonly hostKeyPolicy;
-    private nextTunnelId;
-    /**
-     * 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;
+    private readonly manager;
+    private readonly sftpService;
+    private readonly tunnelService;
+    private readonly terminalService;
     /**
      * @param store - the host config store.
-     * @param options - engine knobs (defaults applied).
+     * @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).
      */
     constructor(store: HostStoreView, options?: EngineOptions, deps?: EngineDeps);
-    /**
-     * 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.
-     */
+    /** Provide a secret for `alias` for THIS session only (never persisted). */
     setSessionPassword(alias: string, secret: {
         password?: string;
         passphrase?: string;
@@ -208,6 +112,8 @@ export declare class SshEngine {
     } | undefined;
     /** Drop every session secret (e.g. on secretStorage change / lock). */
     clearSessionSecrets(): void;
+    /** 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. */
@@ -223,45 +129,24 @@ export declare class SshEngine {
     /** Aliases with a live pooled transport right now (for connection-state
      *  indicators — the GUI badge colors bound workspaces by it). */
     connectedAliases(): string[];
-    /**
-     * 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.
-     */
+    /** Retire the pooled connection for one alias (optionally its dependents). */
     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.
+     * Record one channel that never acknowledged close after a hard timeout.
+     * Exposed for the exec grace path and for diagnostics/tests.
+     * @param alias - the host the channel belonged to.
+     * @returns true when the pooled transport was drained.
      */
-    private withClient;
-    /** 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. */
-    private resolveEntryAuth;
+    noteLeakedChannel(alias: string): boolean;
+    /** A late channel close: un-count one half-open channel for this alias. */
+    noteChannelClosed(alias: string): void;
+    /** Run one command on `alias` (reusing the pooled connection). */
+    exec(alias: string, command: string, timeoutMs?: number): Promise<import('./protocol.ts').ExecResult>;
+    exec(alias: string, command: string, options: ExecOptions): Promise<import('./protocol.ts').ExecResult>;
     /**
-     * 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.
+     * Run one command against many hosts concurrently. Per-host failures carry
+     * the typed, secret-free fields declared on `ClusterResult`.
      */
-    private connectChain;
-    /** Run one command on `alias` (reusing the pooled connection). */
-    exec(alias: string, command: string, timeoutMs?: number): Promise<ExecResult>;
-    exec(alias: string, command: string, options: ExecOptions): Promise<ExecResult>;
-    /** Run one command against many hosts concurrently. */
     cluster(options: {
         command: string;
         aliases?: string[];
@@ -269,14 +154,9 @@ export declare class SshEngine {
         tags?: string[];
         timeoutMs?: number;
         maxWorkers?: number;
-    }): Promise<ClusterResult[]>;
-    /**
-     * Open one standalone channel on its own connection (never a pooled one).
-     * Shared by openShell/openExec (P1-18): alias lookup, jump chain,
-     * channel-open timeout, idempotent teardown, and late-callback cleanup live
-     * here, so the two public methods keep only their session-specific assembly.
-     */
-    private openStandaloneChannel;
+        /** Aborts every per-host run when the caller disconnects. */
+        signal?: AbortSignal;
+    }): Promise<import('./protocol.ts').ClusterResult[]>;
     /** Open a PTY shell session for the web terminal (standalone connection). */
     openShell(alias: string, size: {
         cols: number;
@@ -288,36 +168,22 @@ export declare class SshEngine {
      * can never tear down a pooled exec/tunnel sharing the alias.
      */
     openExec(alias: string, command: string): Promise<ExecSession>;
-    /** Upload one local file (or directory tree) to a remote path. */ upload(alias: string, localPath: string, remotePath: string, recursive: boolean, onProgress?: (progress: TransferProgress) => void): Promise<{
+    /** Upload one local file (or directory tree) to a remote path. */
+    upload(alias: string, localPath: string, remotePath: string, recursive: boolean, onProgress?: (progress: TransferProgress) => void, signal?: AbortSignal): Promise<{
         bytes: number;
         files: number;
     }>;
     /** Download one remote file to a local path. */
-    download(alias: string, remotePath: string, localPath: string, onProgress?: (progress: TransferProgress) => void): Promise<{
+    download(alias: string, remotePath: string, localPath: string, onProgress?: (progress: TransferProgress) => void, signal?: AbortSignal): Promise<{
         bytes: number;
     }>;
     /** List a remote directory (file browser). Bounded by a timeout so a
      *  stalled SFTP request fails instead of leaving the file tree spinning. */
-    ls(alias: string, path: string): Promise<import('./protocol.ts').RemoteDirEntry[]>;
-    /**
-     * Resolve many remote paths to their canonical form in one SFTP pass
-     * (P1-26): one lease + one batch of `sftp.realpath` calls instead of N
-     * `realpath` execs. A path that cannot resolve (dangling symlink, vanished
-     * entry) fails the whole batch — callers treat an unresolvable listing as
-     * an error rather than silently using an uncanonical path.
-     */
-    realpaths(alias: string, remotePaths: readonly string[]): Promise<string[]>;
-    /**
-     * Classify readdir entries, following symlinks so a link to a directory
-     * (e.g. AutoDL's /root/autodl-tmp) lists as a directory instead of 'other'.
-     * Symlinks are stat'd in PARALLEL batches: serializing them turns a conda /
-     * venv bin full of links into N round-trips (seconds to tens of seconds on a
-     * slow link) — batching keeps it to a handful of round-trips. The whole pass
-     * is bounded by ls()'s timeout.
-     */
-    private classifyEntries;
+    ls(alias: string, path: string, signal?: AbortSignal): Promise<import('./protocol.ts').RemoteDirEntry[]>;
+    /** Resolve many remote paths to their canonical form in one SFTP pass. */
+    realpaths(alias: string, remotePaths: readonly string[], signal?: AbortSignal): Promise<string[]>;
     /** Stat one remote path (file browser / conflict checks). Bounded by a timeout. */
-    stat(alias: string, remotePath: string): Promise<{
+    stat(alias: string, remotePath: string, signal?: AbortSignal): Promise<{
         type: 'dir' | 'file' | 'other';
         size: number;
         mtimeMs: number;
@@ -327,7 +193,7 @@ export declare class SshEngine {
      * Lstat one remote path without following the final symlink. Returns
      * undefined when the path is absent (the fs seam's lstat contract).
      */
-    lstat(alias: string, remotePath: string): Promise<{
+    lstat(alias: string, remotePath: string, signal?: AbortSignal): Promise<{
         type: 'file' | 'directory' | 'symlink' | 'other';
         size: number;
         mtimeMs: number;
@@ -336,20 +202,15 @@ export declare class SshEngine {
     /**
      * Open a remote file read stream (the fs seam's streamText). The returned
      * stream must be consumed or destroyed; the pooled connection stays busy
-     * for the stream's lifetime.
-     */
-    /**
-     * Open a remote file read stream (the fs seam's streamText). The returned
-     * stream must be consumed or destroyed; the pooled connection stays busy
-     * for the stream's lifetime (P0-10: a 'stream' lease, released on
+     * for the stream's lifetime (a 'stream' lease, released on
      * end/close/error/destroy — not when this function returns).
      */
-    readStream(alias: string, remotePath: string): Promise<import('node:stream').Readable>;
+    readStream(alias: string, remotePath: string, signal?: AbortSignal): Promise<import('node:stream').Readable>;
     /**
      * Read one remote file fully into memory (text or binary) with its mtime.
      * The workspace plugin's text gate (UTF-8 + size caps) lives on its caller.
      */
-    readFile(alias: string, remotePath: string): Promise<{
+    readFile(alias: string, remotePath: string, maxBytes?: number, signal?: AbortSignal): Promise<{
         content: Buffer;
         mtime: number;
         size: number;
@@ -357,14 +218,13 @@ export declare class SshEngine {
     /**
      * Write one remote file from memory (parents are created). When
      * `expectedMtime` is given, a stat-then-write conflict check throws before
-     * any byte is written (the GUI and the workspace tools use it for
-     * overwrite protection).
+     * any byte is written (overwrite protection for the GUI and workspace tools).
      */
-    writeFile(alias: string, remotePath: string, content: Buffer, expectedMtime?: number): Promise<{
+    writeFile(alias: string, remotePath: string, content: Buffer, expectedMtime?: number, signal?: AbortSignal): Promise<{
         mtime: number;
     }>;
     /** Create a remote directory chain (mkdir -p semantics). */
-    mkdir(alias: string, remotePath: string): Promise<void>;
+    mkdir(alias: string, remotePath: string, signal?: AbortSignal): Promise<void>;
     /**
      * Remove a remote file or directory. Directories require `recursive: true`
      * and are walked depth-first (children first, then the directory itself).
@@ -374,61 +234,31 @@ export declare class SshEngine {
      * recursed into — the old stat/readdir-attr check could delete the link
      * target's contents.
      */
-    rm(alias: string, remotePath: string, recursive?: boolean): Promise<void>;
+    rm(alias: string, remotePath: string, recursive?: boolean, signal?: AbortSignal): Promise<void>;
     /** Rename / move a remote path (mv semantics, same filesystem). */
-    rename(alias: string, fromPath: string, toPath: string): Promise<void>;
-    /** Reject a promise after `ms` (unref'd so it never keeps the process alive).
-     *  `onTimeout` (when given) runs right before the rejection: ssh2 SFTP
-     *  requests have no cancel API, so callers that hold an abort handle (e.g.
-     *  a read stream) destroy it here — otherwise the underlying transfer would
-     *  keep running (and, for reads, keep buffering) after the caller was told
-     *  it timed out. */
-    private withTimeout;
-    /** Stat wrapper (one SFTP stat call). */
-    private sftpStat;
-    /** Lstat wrapper (does NOT follow symlinks — the deletion safety gate). */
-    private sftpLstat;
-    /**
-     * The (cached) SFTP channel for a pooled client. `Client.sftp()` opens a new
-     * subsystem channel per call, so this memoizes one channel per live client;
-     * when the channel closes the cache entry is dropped so the next call opens
-     * SFTP on the replacement connection. Failed opens are also evicted so a
-     * transient channel failure can be retried.
-     */
-    private sftpFor;
-    /** Create a remote directory chain (stat-then-mkdir per segment). */
-    private ensureRemoteDir;
-    private fastPut;
-    private fastGet;
-    /** Remove one tunnel's transport-failure listener (both events). */
-    private removeTunnelClientFailureListener;
-    /**
-     * Mark every tunnel sharing a failed physical SSH client as failed. Failed
-     * records stay in this.tunnels so listTunnels() exposes the terminal state
-     * and stopTunnel() remains the single place that deletes + releases.
-     */
-    private markTunnelsFailedForClient;
-    /** Start a local port-forward tunnel (listens on 127.0.0.1 only). */
+    rename(alias: string, fromPath: string, toPath: string, signal?: AbortSignal): Promise<void>;
     startTunnel(alias: string, options: {
         remotePort: number;
         remoteHost?: string;
         localPort?: number;
     }): Promise<TunnelInfo>;
-    /** All active tunnels. */
     listTunnels(): TunnelInfo[];
-    /** Stop one tunnel (closes listener and live sockets, releases its lease). */
     stopTunnel(id: string): boolean;
-    /** Stop all tunnels (optionally for one alias). */
     stopAllTunnels(alias?: string): number;
     /** 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): Promise<TestResult>;
-    /** Close every pooled connection and tunnel, and wipe the in-memory
-     *  session password table (secrets are never persisted anywhere). */
+    test(alias: string, signal?: AbortSignal): Promise<import('./protocol.ts').TestResult>;
+    /**
+     * Close every resource this engine owns and wipe the in-memory session
+     * password table (secrets are never persisted anywhere).
+     *
+     * Order: tunnel → terminal → SFTP → connection, so a resource is always
+     * closed before the transport that carries it, and each resource has exactly
+     * one dispose point.
+     */
     dispose(): void;
 }
-export {};
 //# sourceMappingURL=engine.d.ts.map

package/lib/types/ssh/known-hosts.d.ts

@@ -55,15 +55,20 @@ export declare class KnownHostsStore {
     private load;
     private save;
     lookup(alias: string): KnownHostRecord | undefined;
-    /** First encounter: record as pending (non-destructive re-observe keeps status). */
+    /** First encounter: record as pending. Re-observing keeps the recorded
+     *  status/fingerprint but backfills a previously empty host/port. */
     observe(alias: string, meta: {
         host: string;
         port: number;
         keyType: string;
         fingerprintSha256: string;
     }): void;
-    /** pending → trusted (must match the recorded fingerprint). */
-    trust(alias: string): void;
+    /** pending → trusted (must match the recorded fingerprint). Optional
+     *  host/port backfill completes a record whose first observe had no target. */
+    trust(alias: string, target?: {
+        host?: string;
+        port?: number;
+    }): void;
     /** Forget a host (key rotation /误信 reset → next connect re-TOFU). */
     forget(alias: string): void;
     list(): KnownHostRecord[];
@@ -72,9 +77,21 @@ export declare class KnownHostsStore {
 export declare class HostKeyPolicy {
     private readonly knownHosts;
     constructor(knownHosts: KnownHostsStore);
-    /** Evaluate one server key: trusted / unknown (records pending) / mismatch. */
-    check(alias: string, rawKey: Buffer): HostKeyCheck;
+    /** Evaluate one server key: trusted / unknown (records pending) / mismatch.
+     *  `target` supplies the host/port the engine is actually connecting to so
+     *  the audit record is complete instead of `''`/0. */
+    check(alias: string, rawKey: Buffer, target?: {
+        host?: string;
+        port?: number;
+    }): HostKeyCheck;
 }
+/**
+ * Parse the key type out of a real SSH wire public-key blob. The blob is
+ * `string algorithm, byte[] key` where every string is a 4-byte big-endian
+ * length followed by raw bytes — NOT the `ssh-ed25519 AAAA…` authorized_keys
+ * text form, so a text-oriented decode would always yield 'ssh-unknown'.
+ */
+export declare function keyTypeOf(rawKey: Buffer): string;
 /** Error: the host key is not trusted yet (first encounter, awaiting confirm). */
 export declare class HostKeyUnknownError extends Error {
     readonly fingerprintSha256: string;

package/lib/types/ssh/local-transfer-policy.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Host-side path policy for ssh_upload / ssh_download.
+ *
+ * These tools bridge remote I/O to the DSH host, so accepting an arbitrary
+ * absolute local path would bypass the normal FileSystem sandbox. The only
+ * trusted per-call root available to a tool body is the validated absolute cwd
+ * stored on the invoking Agent's immutable SessionHeader.
+ */
+import type { ToolRunContext } from '@deepseek-ai/dsh-tools';
+export type LocalTransferDirection = 'upload-source' | 'download-destination';
+/**
+ * Validate and canonicalize one local transfer path.
+ *
+ * Uploads must name an existing regular file. Downloads may create the final
+ * file and missing parent directories, but their nearest existing ancestor is
+ * canonicalized so an in-workspace symlink/junction cannot redirect the write
+ * outside the session root.
+ */
+export declare function secureLocalTransferPath(exec: ToolRunContext, localPath: string, direction: LocalTransferDirection): string;
+//# sourceMappingURL=local-transfer-policy.d.ts.map

package/lib/types/ssh/plugin.d.ts

@@ -15,27 +15,20 @@ import type { SshEngine } from './engine.ts';
 /** Settings namespace of the SSH capability. Kept as 'dsh-ssh' so existing
  *  user settings survive the package merge unchanged. */
 export declare const SSH_SETTINGS_NAMESPACE = "dsh-ssh";
-/** SSH-capability config, validated by the same-named schemastery schema. */
+/** SSH-capability config, validated by the same-named schemastery schema.
+ *  `secretStorage` is deliberately NOT a key here: the mode decides which
+ *  objects are constructed at plugin load, so it is a single source in the
+ *  top-level plugin config (`Config.secretStorage`). A value left in this
+ *  namespace by hand is reported as drift by src/index.ts, never applied. */
 export interface SshConfig {
     /** When true (default), a system-prompt section announces the SSH capability. */
     announceToAgent?: boolean;
     /** Master switch for the SSH surfaces (routes, tools, prompt section). */
     enabled?: boolean;
-    /**
-     * Secret storage mode:
-     * - 'none' (default): passwords/passphrases are NEVER persisted; each
-     *   session's first connection prompts for them (VSCode Remote-SSH style)
-     *   and they live in memory (session password table) for the connection
-     *   pool lifetime (idle 30 min auto-disconnect; new terminals reuse it).
-     * - 'vault': store secrets encrypted at rest (AES-256-GCM) under a master
-     *   password / DSH_CREDENTIAL_PASSWORD; for headless agents that must run
-     *   password hosts unattended.
-     */
-    secretStorage?: 'none' | 'vault';
 }
 export declare const SshConfig: z<SshConfig>;
 /** Model-facing announcement: SSH operations capability, capabilities, limits. */
-export declare const SSH_GUIDANCE = "\u672C\u673A\u5DF2\u5B89\u88C5 dsh-hardssh \u63D2\u4EF6\uFF08\u5185\u5EFA DSH \u8FDC\u7A0B SSH \u8FD0\u7EF4\uFF09\uFF1A\u4FA7\u8FB9\u680F\u300CSSH\u300D\u5165\u53E3\uFF1BSSH \u8FD0\u7EF4\u4E0E SSH \u5DE5\u4F5C\u533A\u5728 dsh-hardssh \u4E2D\u7EDF\u4E00\u7EF4\u62A4\u3002\u80FD\u529B\uFF1A\u4E3B\u673A\u914D\u7F6E\u5B58 ~/.dsh/dsh-ssh.json\uFF08\u53EF\u4ECE ~/.ssh/config \u5BFC\u5165\uFF09\uFF1B\u6301\u4E45\u8FDE\u63A5\u6C60\u590D\u7528\u957F\u8FDE\u63A5\uFF08\u7A7A\u95F2 30 \u5206\u949F\u81EA\u52A8\u65AD\u5F00\uFF09\uFF1Bssh_list \u5217\u51FA\u4E3B\u673A\u3001ssh_exec \u6267\u884C\u8FDC\u7A0B\u547D\u4EE4\u3001ssh_upload/ssh_download \u4F20\u8F93\u6587\u4EF6\u3001ssh_tunnel \u672C\u5730\u7AEF\u53E3\u8F6C\u53D1\uFF08\u8BBF\u95EE\u8FDC\u7A0B\u6570\u636E\u5E93/\u5185\u7F51\u670D\u52A1\uFF09\u3001ssh_cluster \u96C6\u7FA4\u5E76\u53D1\u6267\u884C\uFF1B\u652F\u6301\u5BC6\u94A5/\u5BC6\u7801\u8BA4\u8BC1\u3001passphrase \u5BC6\u94A5\u4E0E ProxyJump \u8DF3\u677F\u673A\uFF1BWeb \u7EC8\u7AEF\u8D70 WebSocket\u3002\u9650\u5236\uFF1A\u4E3B\u673A\u64CD\u4F5C\u7531\u7528\u6237\u5728 GUI \u4E2D\u914D\u7F6E\u540E agent \u65B9\u53EF\u4F7F\u7528\uFF1B\u5BC6\u7801\u4EE5\u660E\u6587\u5B58\u5728\u7528\u6237\u4E3B\u76EE\u5F55\u79C1\u6709\u6587\u4EF6\uFF08\u6743\u9650 0600\uFF09\uFF1B\u547D\u4EE4\u8F93\u51FA\u539F\u6837\u8FD4\u56DE\u3001\u53EF\u80FD\u542B\u654F\u611F\u4FE1\u606F\uFF1B\u8FDE\u63A5\u5EFA\u7ACB\u5931\u8D25\u4F1A\u81EA\u52A8\u91CD\u8FDE\uFF0C\u4F46\u547D\u4EE4\u6216\u6587\u4EF6\u64CD\u4F5C\u4E00\u65E6\u63D0\u4EA4\u5C31\u4E0D\u4F1A\u81EA\u52A8\u91CD\u8BD5\u2014\u2014\u7ED3\u679C\u4E0D\u660E\u786E\u65F6\u5E94\u5148\u6838\u5B9E\u8FDC\u7AEF\u72B6\u6001\uFF0C\u518D\u51B3\u5B9A\u662F\u5426\u4EBA\u5DE5\u91CD\u8BD5\uFF1B\u4F20\u8F93/\u6267\u884C\u6D88\u8017\u771F\u5B9E\u8FDC\u7A0B\u8D44\u6E90\uFF0C\u5148\u786E\u8BA4\u518D\u64CD\u4F5C\u3002\u7528\u6237\u63D0\u5230\u300CSSH / \u8FDC\u7A0B\u670D\u52A1\u5668 / \u670D\u52A1\u5668\u64CD\u4F5C / \u8DF3\u677F\u673A / \u96A7\u9053 / \u90E8\u7F72 / \u4E0A\u4F20\u4E0B\u8F7D\u300D\u65F6\u5373\u6307\u672C\u63D2\u4EF6\uFF0C\u8BF7\u636E\u6B64\u534F\u4F5C\u3002";
+export declare const SSH_GUIDANCE = "\u672C\u673A\u5DF2\u5B89\u88C5 dsh-hardssh \u63D2\u4EF6\uFF08\u5185\u5EFA DSH \u8FDC\u7A0B SSH \u8FD0\u7EF4\uFF09\uFF1A\u4FA7\u8FB9\u680F\u300CSSH\u300D\u5165\u53E3\uFF1BSSH \u8FD0\u7EF4\u4E0E SSH \u5DE5\u4F5C\u533A\u5728 dsh-hardssh \u4E2D\u7EDF\u4E00\u7EF4\u62A4\u3002\u80FD\u529B\uFF1A\u4E3B\u673A\u914D\u7F6E\u5B58 ~/.dsh/dsh-ssh.json\uFF08\u53EF\u4ECE ~/.ssh/config \u5BFC\u5165\uFF09\uFF1B\u6301\u4E45\u8FDE\u63A5\u6C60\u590D\u7528\u957F\u8FDE\u63A5\uFF08\u7A7A\u95F2 30 \u5206\u949F\u81EA\u52A8\u65AD\u5F00\uFF09\uFF1Bssh_list \u5217\u51FA\u4E3B\u673A\u3001ssh_exec \u6267\u884C\u8FDC\u7A0B\u547D\u4EE4\u3001ssh_upload/ssh_download \u4F20\u8F93\u6587\u4EF6\u3001ssh_tunnel \u672C\u5730\u7AEF\u53E3\u8F6C\u53D1\uFF08\u8BBF\u95EE\u8FDC\u7A0B\u6570\u636E\u5E93/\u5185\u7F51\u670D\u52A1\uFF09\u3001ssh_cluster \u96C6\u7FA4\u5E76\u53D1\u6267\u884C\uFF1B\u652F\u6301\u5BC6\u94A5/\u5BC6\u7801\u8BA4\u8BC1\u3001passphrase \u5BC6\u94A5\u4E0E ProxyJump \u8DF3\u677F\u673A\uFF1BWeb \u7EC8\u7AEF\u8D70 WebSocket\u3002\u9650\u5236\uFF1A\u4E3B\u673A\u64CD\u4F5C\u7531\u7528\u6237\u5728 GUI \u4E2D\u914D\u7F6E\u540E agent \u65B9\u53EF\u4F7F\u7528\uFF1B\u51ED\u636E\u9ED8\u8BA4\u4E0D\u843D\u76D8\uFF08secretStorage=none \u65F6\u4EC5\u5B58\u4E8E\u672C\u8FDB\u7A0B\u5185\u5B58\uFF0C\u6309\u8FDE\u63A5\u5B58\u6D3B\u671F\u590D\u7528\u3001\u8FDE\u63A5\u6C60\u56DE\u6536\u5373\u5931\u6548\uFF1BsecretStorage=vault \u65F6\u4EE5 AES-256-GCM \u52A0\u5BC6\u5B58\u4E8E\u672C\u673A vault \u6587\u4EF6\uFF0C`DSH_CREDENTIAL_PASSWORD` \u81EA\u52A8\u89E3\u9501\u9ED8\u8BA4\u5173\u95ED\uFF0C\u9700 vaultAutoUnlock: env \u663E\u5F0F\u5F00\u542F\uFF09\uFF1B\u547D\u4EE4\u8F93\u51FA\u4E0E\u9519\u8BEF\u7ECF\u8FC7\u51ED\u636E\u8131\u654F\uFF08\u5DF2\u63ED\u793A/\u4F1A\u8BDD\u5185\u7684\u5BC6\u7801\u4F1A\u88AB\u66FF\u6362\uFF09\uFF0C\u4F46\u4ECD\u53EF\u80FD\u542B\u5176\u5B83\u654F\u611F\u4FE1\u606F\uFF1B\u8FDE\u63A5\u5EFA\u7ACB\u5931\u8D25\u4F1A\u81EA\u52A8\u91CD\u8FDE\uFF0C\u4F46\u547D\u4EE4\u6216\u6587\u4EF6\u64CD\u4F5C\u4E00\u65E6\u63D0\u4EA4\u5C31\u4E0D\u4F1A\u81EA\u52A8\u91CD\u8BD5\u2014\u2014\u7ED3\u679C\u4E0D\u660E\u786E\u65F6\u5E94\u5148\u6838\u5B9E\u8FDC\u7AEF\u72B6\u6001\uFF0C\u518D\u51B3\u5B9A\u662F\u5426\u4EBA\u5DE5\u91CD\u8BD5\uFF1B\u4F20\u8F93/\u6267\u884C\u6D88\u8017\u771F\u5B9E\u8FDC\u7A0B\u8D44\u6E90\uFF0C\u5148\u786E\u8BA4\u518D\u64CD\u4F5C\u3002\u7528\u6237\u63D0\u5230\u300CSSH / \u8FDC\u7A0B\u670D\u52A1\u5668 / \u670D\u52A1\u5668\u64CD\u4F5C / \u8DF3\u677F\u673A / \u96A7\u9053 / \u90E8\u7F72 / \u4E0A\u4F20\u4E0B\u8F7D\u300D\u65F6\u5373\u6307\u672C\u63D2\u4EF6\uFF0C\u8BF7\u636E\u6B64\u534F\u4F5C\u3002";
 /** Shared instances the SSH surfaces run on. */
 export interface SshCapabilityDeps {
     store: import('./store.ts').SecureHostStore;
@@ -44,8 +37,10 @@ export interface SshCapabilityDeps {
     knownHosts?: import('./known-hosts.ts').KnownHostsStore;
     /** Credential vault; absent → vault endpoints disabled. */
     vault?: import('./vault.ts').Vault;
-    /** SSH-bound workspace ledger (host-delete reference guard). */
-    ledger?: import('../ledger.ts').SshWorkspaceLedger;
+    /** SSH-bound workspace record source (host-delete reference guard). The
+     *  legacy ledger in legacy mode, the generic WorkspaceCore-backed projection
+     *  store in the default generic mode. */
+    ledger?: import('../backend.ts').WorkspaceStoreView;
 }
 /**
  * Mount the SSH operations surfaces (routes, tools, settings, prompt) against