ssh2.d.ts

// Type definitions for ssh2
// Project: https://github.com/mscdex/ssh2
// Definitions by: Qubo <https://github.com/tkQubo>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped

/// <reference path="../node/node.d.ts" />

declare module "ssh2" {
    import stream = require('stream');

    namespace ssh2 {
        interface Client extends NodeJS.EventEmitter {
            Server: ServerStatic;
            new(): Client;
            /**
             * SFTPStream.STATUS_CODE from ssh2-streams.
             */
            SFTP_STATUS_CODE: Sftp.StatusCode;
            /**
             * SFTPStream.OPEN_MODE from ssh2-streams.
             */
            SFTP_OPEN_MODE: Sftp.OpenMode;
            //TODO: Type ssh2-streams
            /**
             * utility methods from ssh2-streams.
             */
            utils: Utils;

            connect(config: ConnectConfig): void;
            end(): void;
            destroy(): void;
            exec(command: string, options: ExecOption, callback: ChannelCallback): boolean;
            exec(command: string, callback: ChannelCallback): boolean;
            shell(window: boolean|PseudoTtySettings, options: boolean|number|X11Settings, callback: ChannelCallback): boolean;
            shell(window: boolean|PseudoTtySettings, callback: ChannelCallback): boolean;
            shell(callback: ChannelCallback): boolean;
            subsys(subsystem: string, callback: ChannelCallback): boolean;
            sftp(callback: SftpCallback): boolean;
            forwardIn(bindAddr: string, bindPort: number, callback?: ForwardInCallback): boolean;
            unforwardIn(bindAddr: string, bindPort: number, callback?: ErrorCallback): boolean;
            forwardOut(srcIP: string, srcPort: number, dstIP: string, dstPort: number, callback: ChannelCallback): boolean;
            openssh_noMoreSessions(callback?: ErrorCallback): boolean;
            openssh_forwardInStreamLocal(socketPath: string, callback?: ErrorCallback): boolean;
            openssh_unforwardInStreamLocal(socketPath: string, callback?: ErrorCallback): boolean;
            openssh_forwardOutStreamLocal(socketPath: string, callback?: ChannelCallback): boolean;
        }

        interface ConnectConfig {
            /**
             * @description Hostname or IP address of the server.
             * @default 'localhost'
             */
            host?: string;
            /**
             * @description Port number of the server.
             * @default 22
             */
            port?: number;
            /**
             * @description Only connect via resolved IPv4 address for `host`.
             * @default false
             */
            forceIPv4?: boolean;
            /**
             * @description Only connect via resolved IPv6 address for `host`.
             * @default false
             */
            forceIPv6?: boolean;
            /**
             * @description 'md5' or 'sha1'. The host's key is hashed using this method and passed to the **hostVerifier** function.
             * @default (none)
             */
            hostHash?: string;
            /**
             * @description Function that is passed a string hex hash of the host's key for verification purposes.
             * Return `true` to continue with the handshake or `false` to reject and disconnect.
             */
            hostVerifier?: (keyHash: string) => boolean;
            /**
             * @description Username for authentication.
             */
            username?: string;
            /**
             * @description Password for password-based user authentication.
             */
            password?: string;
            /**
             * @description Path to ssh-agent's UNIX socket for ssh-agent-based user authentication.
             * Windows users: set to 'pageant' for authenticating with Pageant or (actual) path to a cygwin "UNIX socket."
             */
            agent?: string;
            /**
             * @description Buffer or string that contains a private key for either key-based or hostbased user authentication (OpenSSH format).
             */
            privateKey?: Buffer|string;
            /**
             * @description For an encrypted private key, this is the passphrase used to decrypt it.
             */
            passphrase?: string;
            /**
             * @description Along with **localUsername** and **privateKey**, set this to a non-empty string for hostbased user authentication.
             */
            localHostname?: string;
            /**
             * @description Along with **localHostname** and **privateKey**, set this to a non-empty string for hostbased user authentication.
             */
            localUsername?: string;
            /**
             * @description Try keyboard-interactive user authentication if primary user authentication method fails.
             * If you set this to `true`, you need to handle the `keyboard-interactive` event.
             */
            tryKeyboard?: boolean;
            /**
             * @description How often (in milliseconds) to send SSH-level keepalive packets to the server
             * (in a similar way as OpenSSH's ServerAliveInterval config option). Set to 0 to disable.
             * @default 0
             */
            keepaliveInterval?: number;
            /**
             * @description How many consecutive, unanswered SSH-level keepalive packets that can be sent to the server
             * before disconnection (similar to OpenSSH's ServerAliveCountMax config option).
             * @default 3
             */
            keepaliveCountMax?: number;
            /**
             * @description How long (in milliseconds) to wait for the SSH handshake to complete.
             * @default 20000
             */
            readyTimeout?: number;
            /**
             * @description Performs a strict server vendor check before sending vendor-specific requests,
             * etc. (e.g. check for OpenSSH server when using `openssh_noMoreSessions()`)
             * @default true
             */
            strictVendor?: boolean;
            /**
             * A ReadableStream to use for communicating with the server instead of creating and using a new TCP connection (useful for connection hopping).
             */
            sock?: NodeJS.ReadableStream;
            /**
             * @description Set to `true` to use OpenSSH agent forwarding (`auth-agent@openssh.com`) for the life of the connection. `agent` must also be set to use this feature.
             * @default false
             */
            agentForward?: boolean;
            /**
             * @description Set this to a function that receives a single string argument to get detailed (local) debug information.
             */
            debug?: (information: string) => any;
        }

        interface ExecOption {
            /**
             * @description An environment to use for the execution of the command.
             */
            env?: any;
            /**
             * @description Set to true to allocate a pseudo-tty with defaults, or an object containing specific pseudo-tty settings
             * (see 'Pseudo-TTY settings'). Setting up a pseudo-tty can be useful when working with remote processes
             * that expect input from an actual terminal (e.g. sudo's password prompt).
             */
            pty?: boolean|PseudoTtySettings;
            /**
             * @description Set to true to use defaults below, set to a number to specify a specific screen number,
             * or an object.
             */
            x11?: boolean|number|X11Settings;
        }

        interface X11Settings {
            /**
             * Allow just a single connection?
             * @default false
             */
            single?: boolean;
            /**
             * Screen number to use
             * @default 0
             */
            screen?: number;
        }

        interface PseudoTtySettings {
            /**
             * @description * Number of rows
             * @default 24
             */
            rows?: number;
            /**
             * @description * Number of columns
             * @default 80
             */
            cols?: number;
            /**
             * @description * Height in pixels
             * @default 480
             */
            height?: number;
            /**
             * @description * Width in pixels
             * @default 640
             */
            width?: number;
            /**
             * @description The value to use for $TERM
             * @default 'vt100'
             */
            term?: string;
        }

        interface ForwardInCallback {
            (err?: Error, bindPort?: number): void;
        }

        interface ChannelCallback {
            (err?: Error, channel?: Channel): void;
        }

        interface SftpCallback {
            (err?: Error, sftp?: Sftp.Wrapper): void;
        }

        interface ErrorCallback {
            (err?: Error): void;
        }

        interface Channel extends stream.Duplex {
            new(info?: any, client?: any, options?: any): Channel;
            eof(): boolean;
            close(): boolean;
            destroy(): void;
            setWindow(rows: number, cols: number, height: number, width: number): boolean;
            signal(signalName: string): boolean;
            exit(name: string, coreDumped: boolean, msg: string): boolean;
            exit(status: number): boolean;
            stderr?: ServerStderr;
        }

        interface ServerStderr extends NodeJS.WritableStream {
            new(channel: Channel): ServerStderr;
        }

        interface ServerStatic {
            new(config: ServerConfig, listener?: any): Server;
            createServer(config: ServerConfig, listener?: any): Server;
            KEEPALIVE_INTERVAL: number;
            KEEPALIVE_CLIENT_INTERVAL: number;
            KEEPALIVE_CLIENT_COUNT_MAX: number;
        }

        interface Server extends NodeJS.EventEmitter {
            listen(port: number, hostname?: string, backlog?: number, callback?: Function): Server;
            listen(port: number, hostname?: string, callback?: Function): Server;
            listen(path: string, callback?: Function): Server;
            listen(handle: any, listeningListener?: Function): Server;
            address(): { port: number; family: string; address: string; };
            getConnections(callback: any): any; //TODO: No type
            close(callback?: Function): Server;
            ref(): void;
            unref(): void;
        }

        interface ServerConfig {
            /**
             * @description Buffer or string that contains the host private key (OpenSSH format).
             */
            privateKey: Buffer|string;
            /**
             * @description For an encrypted host private key, this is the passphrase used to decrypt it.
             */
            passphrase?: string;
            /**
             * @description A message that is sent to clients immediately upon connection, before handshaking begins.
             */
            banner?: string;
            /**
             * @description A custom server software name/version identifier.
             * @default 'ssh2js' + moduleVersion + 'srv'
             */
            indent?: string;
            /**
             * @description This is the highWaterMark to use for the parser stream.
             * @default 32 * 1024
             */
            highWaterMark?: number;
            /**
             * @description Set this to a function that receives a single string argument to get detailed (local) debug information.
             */
            debug?: (information: string) => any;
        }

        // utility methods from ssh2-streams.
        interface Utils {
            iv_inc: Function;
            isStreamCipher: Function;
            isGCM: Function;
            readInt: Function;
            readString: Function;
            parseKey: Function;
            genPublicKey: Function;
            convertPPKPrivate: Function;
            verifyPPKMAC: Function;
            decryptKey: Function;
        }

        namespace Sftp {
            // SFTPStream.STATUS_CODE from ssh2-streams.
            interface StatusCode {
                OK: number;
                EOF: number;
                NO_SUCH_FILE: number;
                PERMISSION_DENIED: number;
                FAILURE: number;
                BAD_MESSAGE: number;
                NO_CONNECTION: number;
                CONNECTION_LOST: number;
                OP_UNSUPPORTED: number;
            }

            // SFTPStream.OPEN_MODE from ssh2-streams.
            interface OpenMode {
                READ: number;
                WRITE: number;
                APPEND: number;
                CREAT: number;
                TRUNC: number;
                EXCL: number;
            }

            interface Attributes {
                mode: number;
                uid: number;
                gid: number;
                size: number;
                atime: number;
                mtime: number;
            }
            interface InputAttributes {
                mode?: number;
                uid?: number;
                gid?: number;
                size?: number;
                atime?: number;
                mtime?: number;
            }
            interface Stats extends Attributes {
                isDirectory(): boolean;
                isFile(): boolean;
                isBlockDevice(): boolean;
                isCharacterDevice(): boolean;
                isSymbloicLink(): boolean;
                isFIFO(): boolean;
                isSocket(): boolean;
            }

            interface Wrapper extends NodeJS.EventEmitter {
                fastGet(remotePath: string, localPath: string, callback: (err: any) => void): void;
                fastGet(remotePath: string, localPath: string, options: TransferOptions, callback: (err: any) => void): void;
                fastPut(localPath: string, remotePath: string, callback: (err: any) => void): void;
                fastPut(localPath: string, remotePath: string, options: TransferOptions, callback: (err: any) => void): void;

                createReadStream(path: string, options?: ReadStreamOptions): stream.Readable;
                createWriteStream(path: string, options?: WriteStreamOptions): stream.Writable;
                open(filename: string, mode: string, callback: (err: any, handle: Buffer) => void): boolean;
                open(filename: string, mode: string, attributes: InputAttributes, callback: (err: any, handle: Buffer) => void): boolean;
                close(handle: Buffer, callback: (err: any) => void): boolean;
                readData(handle: Buffer, buffer: Buffer, offset: number, length: number, position: number,
                        callback: (err: any, bytesRead: number, buffer: Buffer, position: number) => void): boolean;
                writeData(handle: Buffer, buffer: Buffer, offset: number, length: number, position: number,
                        callback: (err: any) => void): boolean;
                fstat(handle: Buffer, callback: (err: any, stats: Stats) => void): boolean;
                fsetstat(handle: Buffer, attributes: InputAttributes, callback: (err: any) => void): boolean;
                futimes(handle: Buffer, atime: number | Date, mtime: number | Date, callback: (err: any) => void): boolean;
                fchown(handle: Buffer, uid: number, gid: number, callback: (err: any) => void): boolean;
                fchmod(handle: Buffer, mode: number | string, callback: (err: any) => void): boolean;
                opendir(path: string, callback: (err: any, handle: Buffer) => void): boolean;
                readdir(location: string | Buffer, callback: (err: any, list: ReadDirItem[]) => void): boolean;
                unlink(path: string, callback: (err: any) => void): boolean;
                rename(srcPath: string, destPath: string, callback: (err: any) => void): boolean;
                mkdir(path: string, callback: (err: any) => void): boolean;
                mkdir(path: string, attributes: InputAttributes, callback: (err: any) => void): boolean;
                rmdir(path: string, callback: (err: any) => void): boolean;
                stat(path: string, callback: (err: any, stats: Stats) => void): boolean;
                lstat(path: string, callback: (err: any, stats: Stats) => void): boolean;
                setstat(path: string, attributes: InputAttributes, callback: (err: any) => void): boolean;
                utimes(path: string, atime: number | Date, mtime: number | Date, callback: (err: any) => void): boolean;
                chown(path: string, uid: number, gid: number, callback: (err: any) => void): boolean;
                chmod(path: string, mode: number | string, callback: (err: any) => void): boolean;
                readlink(path: string, callback: (err: any, target: string) => void): boolean;
                symlink(targetPath: string, linkPath: string, callback: (err: any) => void): boolean;
                realpath(path: string, callback: (err: any, absPath: string) => void): boolean;

                ext_openssh_rename(srcPath: string, destPath: string, callback: (err: any) => void): boolean;
                ext_openssh_statvfs(path: string, callback: (err: any, fsInfo: any) => void): boolean;
                ext_openssh_fstatvfs(handle: Buffer, callback: (err: any, fsInfo: any) => void): boolean;
                ext_openssh_hardlink(targetPath: string, linkPath: string, callback: (err: any) => void): boolean;
                ext_openssh_fsync(handle: Buffer, callback: (err: any, fsInfo: any) => void): boolean;
            }

            interface TransferOptions {
                concurrency?: number;
                chunkSize?: number;
                step?: (total_transferred: number, chunk: number, total: number) => void;
            }
            interface ReadStreamOptions {
                flags?: string;
                encoding?: string;
                handle?: Buffer;
                mode?: number;
                autoClose?: boolean;
                start?: number;
                end?: number;
            }
            interface WriteStreamOptions {
                flags?: string;
                encoding?: string;
                mode?: number;
            }
            interface ReadDirItem {
              filename: string;
              longname: string;
              attrs: Attributes;
            }
        }
    }

    var ssh2: ssh2.Client;

    export = ssh2;
}