ssh_core #

ssh_core is an experimental Dart SSH client core that focuses on protocol building blocks rather than a single monolithic client implementation.

It defines clear boundaries between transport, authentication, channels, sessions, PTY handling, exec, SFTP, and port forwarding so higher-level packages or applications can compose the pieces they need.

Status #

This repository is public, but it is still not ready for use.

Current status:

• the package is published on pub.flutter-io.cn as an experimental prerelease
• it is useful for SSH protocol exploration and interoperability work
• it is not ready for production use or general application integration yet
• the public API is intentionally small, but some low-level transport details are still evolving

What It Is #

• A Dart-first SSH client core with separable modules
• A transport layer with real secure socket support
• A protocol toolkit for auth, channels, sessions, SFTP, and forwarding
• A codebase aimed at incremental implementation rather than big rewrites

What It Is Not #

• A polished end-user SSH CLI
• A stable 1.0 API
• A full interoperability matrix across every SSH server and algorithm variant
• A replacement for OpenSSH

Highlights #

• SshClient orchestration with injectable transport/auth/session services
• SshSecureSocketTransport with:
  • Curve25519 key exchange
  • Ed25519 / RSA / ECDSA host-key verification
  • chacha20-poly1305@openssh.com
  • aes128-ctr, aes192-ctr, aes256-ctr
  • hmac-sha2-256, hmac-sha2-512
  • zlib and zlib@openssh.com
  • mid-session rekeying
• Packet-backed channel, shell, exec, SFTP, and forwarding services
• Local, remote, and dynamic TCP port forwarding bridges
• Focused tests plus a package-level smoke test
• A live dart:io example via SshIoClientFactory

Getting Started #

The package is published on pub.flutter-io.cn, but it is still not ready for general use. Treat the current release as an experimental prerelease for protocol work and early evaluation.

Use a hosted dependency when consuming a published release:

dependencies:
  ssh_core: ^0.1.0-dev.2

For GitHub-based integration, depend on the repository directly:

dependencies:
  ssh_core:
    git:
      url: https://github.com/Atrac613/ssh_core.git

For local development, a path dependency is still convenient:

dependencies:
  ssh_core:
    path: ../ssh_core

Quick Start #

import 'package:ssh_core/ssh_core.dart';

Future<void> main() async {
  final trustedHostKey = SshHostKey.decode(
    (SshPayloadWriter()
          ..writeString('ssh-ed25519')
          ..writeStringBytes(const [1, 2, 3, 4, 5, 6]))
        .toBytes(),
  );

  final client = SshClient(
    config: SshClientConfig(
      host: 'example.com',
      username: 'demo',
      hostKeyVerifier: SshStaticHostKeyVerifier(
        trustedKeys: <SshTrustedHostKey>[
          SshTrustedHostKey(host: 'example.com', hostKey: trustedHostKey),
        ],
      ),
    ),
    authMethods: const <SshAuthMethod>[
      SshPasswordAuthMethod(password: 'secret'),
    ],
    transport: DemoTransport(hostKey: trustedHostKey),
    authenticator: DemoAuthenticator(),
    channelFactory: DemoChannelFactory(),
    sessionManager: DemoSessionManager(),
    execService: DemoExecService(),
    sftpSubsystem: DemoSftpSubsystem(),
    portForwardingService: DemoPortForwardingService(),
  );

  await client.connect();
  final result = await client.exec('uname -a');
  print(result.stdoutText.trim());
  await client.close();
}

For complete examples:

• example/ssh_core_example.dart: fake/demo wiring that compiles quickly
• example/ssh_core_io_example.dart: live dart:io example built on SshIoClientFactory

Public API #

The main package entry points are:

• package:ssh_core/ssh_core.dart
• package:ssh_core/ssh_core_io.dart

Primary public surfaces:

• SshClient: top-level orchestration
• SshTransport / SshPacketTransport: transport contracts
• SshSecureSocketTransport: real secure dart:io transport
• SshAuthenticator and protocol auth helpers
• SshPacketChannelFactory: packet-backed channel multiplexer
• SshProtocolSessionManager: shell sessions with PTY/env requests
• SshProtocolExecService: non-interactive command execution
• SshProtocolSftpSubsystem: packet-backed SFTP client
• SshIoPortForwardingService: local/remote/dynamic forwarding bridges
• SshIoClientFactory: convenience wiring for live clients

Transport Coverage #

Transport primitives currently include:

• SSH identification banner parsing and exchange
• packet framing and payload codecs
• KEXINIT, ECDH init/reply, NEWKEYS, disconnect, and ext-info messages
• algorithm negotiation helpers
• host-key parsing and verification helpers
• exchange-hash and key-derivation helpers
• encrypted packet protection for AES-CTR/HMAC and ChaCha20-Poly1305

Not implemented yet:

• strict-kex / full Terrapin-oriented transport hardening
• broader KEX coverage beyond the current Curve25519 baseline
• broader cipher / MAC coverage beyond the current explicit matrix

Compatibility Matrix #

Current secure transport interoperability is intentionally narrow and explicit:

Repository Layout #

• lib/ssh_core.dart: main public exports
• lib/ssh_core_io.dart: dart:io-specific exports
• lib/src/transport/: handshake, crypto, packet protection, secure transport
• lib/src/auth/: auth models and protocol authenticator
• lib/src/channels/: channel contracts and packet-backed implementation
• lib/src/sessions/: shell/session abstractions and helpers
• lib/src/exec/: non-interactive exec abstractions and implementation
• lib/src/sftp/: SFTP contracts and packet-backed subsystem
• lib/src/forwarding/: forwarding contracts, protocol helpers, IO bridges
• example/: usage examples
• test/: focused tests
• tool/smoke_test.dart: lightweight end-to-end sanity check

Development #

Run the standard verification set:

dart format .
dart analyze
dart test
dart run tool/smoke_test.dart

GitHub Actions runs the same checks in .github/workflows/dart.yml.

If you want to contribute, see CONTRIBUTING.md. Please also follow the lightweight expectations in CODE_OF_CONDUCT.md.

Roadmap #

Now #

• finish the in-flight transport hardening work around strict-kex, ext-info, and clearer disconnect/error surfacing
• keep strengthening focused tests for transport, auth, session lifecycle, and forwarding shutdown paths
• continue improving OpenSSH interoperability without widening the public API unnecessarily

Next #

• broaden algorithm coverage beyond the current Curve25519 + Ed25519/RSA/ECDSA + ChaCha20/AES-CTR + HMAC-SHA2 baseline
• add more interoperability-focused integration coverage
• tighten host-key trust UX for real applications

Later #

• add advanced forwarding variants beyond TCP local/remote/dynamic bridges
• keep growing the live dart:io examples into copy-pasteable integration recipes
• prepare the package for a first public version and, eventually, pub.flutter-io.cn

Publishing Notes #

Before tagging the first public GitHub release, it is worth checking:

• the README still matches the actual compatibility matrix and examples
• the MIT license remains the intended choice
• GitHub Actions is green on main and on pull requests
• release notes describe the experimental scope and known gaps