@tiphareth/dsh-hardssh 0.1.2

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

@@ -0,0 +1,16 @@
+import type { Client } from 'ssh2';
+/** What kind of resource owns a lease (drives diagnostics and teardown). */
+export type LeaseKind = 'operation' | 'stream' | 'session' | 'tunnel';
+/** One unit of ownership over a pooled SSH connection. */
+export interface ClientLease {
+    readonly alias: string;
+    readonly client: Client;
+    readonly generation: number;
+    readonly kind: LeaseKind;
+    readonly released: boolean;
+    /** Mark the underlying connection broken (surfaces to every holder). */
+    markBroken(error?: unknown): void;
+    /** Idempotent: release this holder's ownership of the connection. */
+    release(): void;
+}
+//# sourceMappingURL=lease.d.ts.map

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

@@ -0,0 +1,57 @@
+import type { Client } from 'ssh2';
+import type { ClientLease, LeaseKind } from './lease.ts';
+export interface AcquireLeaseOptions {
+    kind: LeaseKind;
+    signal?: AbortSignal;
+}
+/** The connection-ownership service (replaces pinned+inFlight bookkeeping). */
+export interface SshConnectionService {
+    acquire(alias: string, options: AcquireLeaseOptions): Promise<ClientLease>;
+    invalidate(alias: string, options?: {
+        includeDependents?: boolean;
+        mode?: 'drain' | 'force';
+    }): void;
+    invalidateAll(): void;
+    /** Aliases currently holding a live pooled transport. */
+    liveAliases(): string[];
+}
+export interface ConnectionPoolOptions {
+    idleTimeoutMs: number;
+    /** Open a fresh SSH connection (with jump chain) for one alias. */
+    connect(alias: string): Promise<{
+        client: Client;
+        hops: Client[];
+    }>;
+    /** Called when a pooled connection is torn down (e.g. drop SFTP cache). */
+    onDispose?(client: Client): void;
+}
+/**
+ * Per-alias connection pool with explicit leases. A connection is swept only
+ * when it has zero leases AND it is idle past the threshold (or draining);
+ * `invalidate` bumps the generation so a half-open handshake can never
+ * re-enter the pool after a config change.
+ */
+export declare class ConnectionPool implements SshConnectionService {
+    private readonly records;
+    private readonly acquireQueue;
+    private readonly generations;
+    private readonly options;
+    private readonly sweepTimer;
+    constructor(options: ConnectionPoolOptions);
+    acquire(alias: string, options: AcquireLeaseOptions): Promise<ClientLease>;
+    invalidate(alias: string, options?: {
+        includeDependents?: boolean;
+        mode?: 'drain' | 'force';
+    }): void;
+    invalidateAll(): void;
+    /** Aliases currently holding a live pooled transport. A record that is
+     *  closed / broken / draining is retired and does not count as connected. */
+    liveAliases(): string[];
+    private acquireRecord;
+    private connectRecord;
+    private createLease;
+    private sweep;
+    private disposeRecord;
+    private closeTransport;
+}
+//# sourceMappingURL=pool.d.ts.map

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

@@ -0,0 +1,434 @@
+/**
+ * The SSH engine: 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.
+ */
+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 { 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).
+ *
+ * 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;
+}
+/** A live PTY shell session. */
+export interface ShellSession {
+    /** Assign to receive remote output. */
+    onData?: (data: Buffer) => void;
+    /** Assign to be notified when the channel closes. */
+    onExit?: (code: number | null, error?: string) => void;
+    /** Write raw input to the shell. */
+    send(data: string): void;
+    /** Resize the remote PTY. */
+    resize(cols: number, rows: number): void;
+    /** Send an SSH signal (e.g. 'TERM', 'KILL') to the remote process group. */
+    signal(name: string): void;
+    /** Close the session and its channel. */
+    close(): void;
+    /** Pause remote output delivery (transport backpressure). */
+    pause(): void;
+    /** Resume remote output delivery. */
+    resume(): void;
+}
+/**
+ * A live streaming exec channel (no PTY): separate stdout/stderr delivery,
+ * stdin writes, SSH signals (TERM/KILL), and an explicit end for the final
+ * input burst. Used by the subprocess capability seam's remote provider.
+ */
+export interface ExecSession extends ShellSession {
+    /** 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. */
+    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.
+ */
+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;
+    /**
+     * @param store - the host config store.
+     * @param options - engine knobs (defaults applied).
+     * @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.
+     */
+    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 every session secret (e.g. on secretStorage change / lock). */
+    clearSessionSecrets(): void;
+    /** Secret-free host list (filtered by the optional query). */
+    list(query?: string): SshHostSummary[];
+    /** One host summary by alias. */
+    find(alias: string): SshHostSummary | undefined;
+    /**
+     * Shared connection/lease service.
+     *
+     * The returned service is owned by this engine. Consumers may acquire
+     * leases or invalidate individual aliases, but must not treat it as a
+     * separately owned pool.
+     */
+    get connections(): SshConnectionService;
+    /** 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.
+     */
+    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.
+     */
+    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;
+    /**
+     * 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.
+     */
+    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[];
+        environment?: string;
+        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;
+    /** Open a PTY shell session for the web terminal (standalone connection). */
+    openShell(alias: string, size: {
+        cols: number;
+        rows: number;
+    }): Promise<ShellSession>;
+    /**
+     * Open a streaming exec channel (no PTY) for the remote subprocess seam.
+     * Like the PTY shell, the channel rides its own connection so closing it
+     * 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<{
+        bytes: number;
+        files: number;
+    }>;
+    /** Download one remote file to a local path. */
+    download(alias: string, remotePath: string, localPath: string, onProgress?: (progress: TransferProgress) => void): 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;
+    /** Stat one remote path (file browser / conflict checks). Bounded by a timeout. */
+    stat(alias: string, remotePath: string): Promise<{
+        type: 'dir' | 'file' | 'other';
+        size: number;
+        mtimeMs: number;
+        mode: number;
+    }>;
+    /**
+     * 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<{
+        type: 'file' | 'directory' | 'symlink' | 'other';
+        size: number;
+        mtimeMs: number;
+        mode: number;
+    } | undefined>;
+    /**
+     * 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
+     * end/close/error/destroy — not when this function returns).
+     */
+    readStream(alias: string, remotePath: string): 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<{
+        content: Buffer;
+        mtime: number;
+        size: number;
+    }>;
+    /**
+     * 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).
+     */
+    writeFile(alias: string, remotePath: string, content: Buffer, expectedMtime?: number): Promise<{
+        mtime: number;
+    }>;
+    /** Create a remote directory chain (mkdir -p semantics). */
+    mkdir(alias: string, remotePath: string): Promise<void>;
+    /**
+     * Remove a remote file or directory. Directories require `recursive: true`
+     * and are walked depth-first (children first, then the directory itself).
+     *
+     * Deletion never follows symlinks: every node is classified with lstat, so
+     * a symlink pointing at a directory is unlinked (only the link), never
+     * recursed into — the old stat/readdir-attr check could delete the link
+     * target's contents.
+     */
+    rm(alias: string, remotePath: string, recursive?: boolean): 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). */
+    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). */
+    dispose(): void;
+}
+export {};
+//# sourceMappingURL=engine.d.ts.map

package/lib/types/ssh/exec/output.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Incremental UTF-8 output collector with a strict BYTE budget.
+ *
+ * The previous implementation compared `text.length` (UTF-16 code units)
+ * against `chunk.length` (bytes) and decoded each chunk in isolation, so
+ * multi-byte characters split across chunks turned into U+FFFD and the
+ * budget was never truly enforced. This collector counts raw input bytes,
+ * decodes across chunk boundaries with StringDecoder, and truncates on a
+ * complete UTF-8 sequence boundary.
+ * @module dsh-ssh/exec/output
+ */
+/** Marker appended when the captured output hits the byte budget. */
+export declare const TRUNCATION_MARKER = "\n[output truncated]";
+/** One captured stream (stdout or stderr). */
+export declare class BoundedUtf8Output {
+    private readonly maxBytes;
+    private readonly decoder;
+    private readonly parts;
+    private _bytesAccepted;
+    private _truncated;
+    private _ended;
+    constructor(maxBytes: number);
+    /** Raw bytes accepted so far (before truncation). */
+    get bytesAccepted(): number;
+    /** True once the byte budget was hit and output was cut. */
+    get truncated(): boolean;
+    append(chunk: Buffer): void;
+    /** The captured text (truncation marker appended when cut). Idempotent. */
+    finish(): string;
+}
+//# sourceMappingURL=output.d.ts.map

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

@@ -0,0 +1,89 @@
+/**
+ * SSH host-key trust store (TOFU): first-connection trust-on-first-use.
+ *
+ * When enabled, the engine refuses to connect to a host whose public-key
+ * fingerprint has not been explicitly trusted: the first encounter records a
+ * `pending` entry and the connection is REJECTED (credentials are never sent
+ * to an unverified host), the operator confirms the fingerprint through the
+ * GUI, and every later connection re-checks the stored fingerprint with a
+ * constant-time comparison.
+ *
+ * The store is deliberately independent of the credentials vault: a
+ * fingerprint is not a secret, so verifying the host needs no unlock, and
+ * Host-Key protectio n can ship (and be tested) before the vault lands.
+ *
+ * @module dsh-hardssh/known-hosts
+ */
+/** One known-host record. */
+export interface KnownHostRecord {
+    alias: string;
+    host: string;
+    port: number;
+    /** Server public-key algorithm (ssh-ed25519, ssh-rsa, …) for display. */
+    keyType: string;
+    /** Canonical fingerprint: 'SHA256:' + base64 (no '=' padding). */
+    fingerprint: string;
+    /** 'pending' = seen once, waiting for explicit trust; 'trusted' = confirmed. */
+    status: 'pending' | 'trusted';
+    firstSeenAt: number;
+    confirmedAt: number | null;
+}
+/** Default file location: <home>/.dsh/ssh-known-hosts.json. */
+export declare function knownHostsPath(): string;
+/** Normalize a fingerprint to the canonical 'SHA256:<b64-no-padding>' form. */
+export declare function normalizeFingerprint(input: string): string;
+/** Constant-time comparison of two fingerprints (canonical form, length-safe). */
+export declare function fingerprintsEqual(a: string, b: string): boolean;
+/** Compute the canonical OpenSSH-style fingerprint of a server key blob. */
+export declare function fingerprintOf(rawKey: Buffer): string;
+/** Host-key check outcome. */
+export type HostKeyCheck = {
+    kind: 'trusted';
+} | {
+    kind: 'unknown';
+    fingerprintSha256: string;
+} | {
+    kind: 'mismatch';
+    expected: string;
+    actual: string;
+};
+/** Persisted host-key trust store (atomic write, 0600). */
+export declare class KnownHostsStore {
+    private readonly path;
+    private records;
+    constructor(filePath?: string);
+    private load;
+    private save;
+    lookup(alias: string): KnownHostRecord | undefined;
+    /** First encounter: record as pending (non-destructive re-observe keeps status). */
+    observe(alias: string, meta: {
+        host: string;
+        port: number;
+        keyType: string;
+        fingerprintSha256: string;
+    }): void;
+    /** pending → trusted (must match the recorded fingerprint). */
+    trust(alias: string): void;
+    /** Forget a host (key rotation /误信 reset → next connect re-TOFU). */
+    forget(alias: string): void;
+    list(): KnownHostRecord[];
+}
+/** Per-alias host-key policy: check a server key against the store. */
+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;
+}
+/** Error: the host key is not trusted yet (first encounter, awaiting confirm). */
+export declare class HostKeyUnknownError extends Error {
+    readonly fingerprintSha256: string;
+    constructor(alias: string, fingerprintSha256: string);
+}
+/** Error: the host key changed since it was trusted (possible MITM / key rotation). */
+export declare class HostKeyMismatchError extends Error {
+    readonly expected: string;
+    readonly actual: string;
+    constructor(alias: string, expected: string, actual: string);
+}
+//# sourceMappingURL=known-hosts.d.ts.map