crussh 0.1.0-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8b47f2f8b5c514209e26b4bd16515ef07bd5ea50c699a442c38db285f240defd
+  data.tar.gz: 414a3722970ff5c5b3876478ee17a98da360a28ae17bb02ad247019dc6f32d6b
+SHA512:
+  metadata.gz: bf17502e616214c3ad7507825876eea67a696961676a6fc3dc720799eb97df4972004e2ff683053dc28ba84c9269e2037f4f5a193f83e369dd0568d6fa6fe7b2
+  data.tar.gz: 10f7bd8cfe125320ab786317a916308b9a5aedf64930aee13bd96e280521e72f2b57d4eef1a711d5b5d4855016be95ea0a566293aeb1fc05a779169dbe122056

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-01-03
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 MSILycanthropy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,371 @@
+# Crussh
+
+[![Gem Version](https://badge.fury.io/rb/crussh.svg)](https://badge.fury.io/rb/crussh)
+[![Build Status](https://github.com/MSILycanthropy/crussh/actions/workflows/main.yml/badge.svg)](https://github.com/MSILycanthropy/crussh/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.3-ruby.svg)](https://www.ruby-lang.org)
+
+A low-level SSH server library for Ruby.
+
+<details>
+  <summary>
+    <strong>Algorithm Support</strong>
+  </summary>
+
+- Ciphers:
+  - `chacha20-poly1305@openssh.com`
+- Key exchanges:
+  - `curve25519-sha256`
+  - `curve25519-sha256@libssh.org`
+- Host keys:
+  - `ssh-ed25519`
+  - `rsa-sha2-256`
+  - `rsa-sha2-512`
+  - `ecdsa-sha2-nistp256`
+  - `ecdsa-sha2-nistp384`
+  - `ecdsa-sha2-nistp521`
+- Authentication:
+  - `none`
+  - `password`
+  - `publickey`
+- Compression:
+  - `none`
+  - `zlib@openssh.com`
+- Channels:
+  - `session`
+  - `direct-tcpip`
+  - `forwarded-tcpip`
+  - `x11`
+- Other: - Strict key exchange (KEX) - `server-sig-algs` extension - `ping@openssh.com` extension - OpenSSH keepalive handling.
+</details>
+
+## Why SSH?
+
+When we think about SSH, we almost exclusively think of it as a tool for remote shell access — `ssh user@server` and you're accessing a remote machine. But SSH is a _protocol_, not just a tool. Like HTTP, and it comes with some really nice benefits out of the box:
+
+- **Encrypted by default** — No certificates to manage, no HTTPS setup
+- **Built-in authentication** — Literally everyone and their mother has an SSH key
+- **Universal client** — Everyone has a beautiful SSH client already
+- **Terminal-native** — We've all got a terminal
+
+You can build all kinds of things over SSH: git servers, file browsers, and even [coffee shops](https://terminal.shop).
+
+Crussh is a library for building these kinds of things in Ruby.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "crussh"
+```
+
+## Quick Start
+
+```ruby
+require "crussh"
+
+class HelloHandler < Crussh::Handler
+  before :log_connect
+  after :log_disconnect
+
+  def handle
+    puts "Hello, #{user}!"
+    puts "Your terminal is #{pty&.term || "unknown"}"
+
+    exit_status(0)
+    close
+  end
+
+  private
+
+  def log_connect
+    logger.info("Client connected", user:)
+  end
+
+  def log_disconnect
+    logger.info("Client disconnected", user:)
+  end
+end
+
+class HelloServer < Crussh::Server
+  configure do |c|
+    c.port = 2222
+
+    # Automatically generate host keys
+    c.generate_host_keys!
+
+    # OR load from a file
+    # c.host_key_files << "/path/to/host_key"
+  end
+
+  authenticate(:none) { true }
+
+  handle :shell, HelloHandler
+end
+
+Sync { HelloServer.run }
+```
+
+Connect with any SSH client:
+
+```bash
+ssh localhost -p 2222
+# => Hello, yourname!
+# => Your terminal is xterm-256color
+```
+
+## Features
+
+- **No OpenSSH** — No OpenSSH dependency. Runs anywhere Ruby runs.
+- **Modern cryptography** — ChaCha20-Poly1305, Curve25519, Ed25519 by default
+- **Async-native** — Built on [Async](https://github.com/socketry/async) for concurrent connections and channels
+- **Clean DSL** — Rails-inspired configuration and authentication
+- **Handler-based** — Separate classes for shell, exec, and subsystem requests
+- **Low-level access** — Drop down to raw channel I/O when you need control
+
+## Authentication
+
+Crussh currently supports `none`, `password` and `publickey` auth. `keyboard-interactive` is planned — PRs welcome!
+
+```ruby
+class MyServer < Crussh::Server
+  authenticate(:none) { |username| username == "guest" }
+
+  authenticate(:password) do |username, password|
+    Users.authenticate(username, password)
+  end
+
+  authenticate(:publickey) do |username, key|
+    AuthorizedKeys.include?(username, key.fingerprint)
+  end
+end
+```
+
+## Handlers
+
+Handlers are plain Ruby classes that process SSH requests. They inherit from `Crussh::Handler` and give you a clean, testable way to organize your logic:
+
+```ruby
+class ShellHandler < Crussh::Handler
+  def handle
+    puts "Welcome, #{user}!"
+    puts "Type 'exit' to quit."
+
+    each_line(prompt: "$ ") do |line|
+      break if line == "exit"
+
+      puts "You typed: #{line}"
+    end
+
+    exit_status(0)
+    close
+  end
+end
+
+class ExecHandler < Crussh::Handler
+  def setup(command)
+    @command = command
+  end
+
+  def handle
+    IO.popen(@command, err: [:child, :out]) do |io|
+      IO.copy_stream(io, channel)
+    end
+
+    exit_status($CHILD_STATUS.exitstatus)
+    close
+  end
+end
+
+class MyServer < Crussh::Server
+  configure do |c|
+    c.port = 2222
+    c.generate_host_keys!
+  end
+
+  authenticate(:publickey) { |user, key| authorized?(user, key) }
+
+  handle :shell, ShellHandler
+  handle :exec, ExecHandler
+end
+```
+
+Handlers have access to:
+
+- `user` — the authenticated username
+- `pty` — PTY info (term, width, height) if requested
+- `env` — environment variables from the client
+- `channel` — the underlying channel for advanced use
+- I/O methods: `puts`, `print`, `gets`, `read`, `write`
+- Lifecycle: `close`, `send_eof`, `exit_status`, `exit_signal`
+
+### Callbacks
+
+Handlers support Rails-style lifecycle callbacks:
+
+```ruby
+class MyHandler < Crussh::Handler
+  before :setup_environment
+  after :cleanup
+  around :with_timing
+
+  rescue_from IOError, with: :handle_disconnect
+
+  def handle
+    # ...
+  end
+
+  private
+
+  def with_timing
+    start = Time.now
+    yield
+  ensure
+    logger.debug("Duration", seconds: Time.now - start)
+  end
+end
+```
+
+## Input Handling
+
+Crussh provides three levels of abstraction for reading events on the channel:
+
+```ruby
+class MyHandler < Crussh::Handler
+  def handle
+    # Low-level: raw SSH events
+    each_event do |event|
+      case event
+      in Channel::Data(data:)
+        # raw bytes from client
+      in Channel::WindowChange(width:, height:)
+        # terminal resized
+      in Channel::EOF
+        # client sent EOF
+      end
+    end
+
+    # Mid-level: parsed keystrokes
+    each_key do |key|
+      case key
+      when :arrow_up then move_up
+      when :enter then submit
+      when String then insert(key)
+      end
+    end
+
+    # High-level: line editing with prompt
+    each_line(prompt: "> ") do |line|
+      process(line)
+    end
+  end
+
+  # Called automatically by each_key/each_line on window resize
+  def resize(width, height)
+    @width = width
+    @height = height
+    redraw
+  end
+end
+```
+
+## Configuration
+
+```ruby
+class MyServer < Crussh::Server
+  configure do |c|
+    # Network
+    c.host = "0.0.0.0"
+    c.port = 2222
+
+    # Keys (generate or load from files)
+    c.generate_host_keys!
+    # c.host_key_files << "/path/to/ssh_host_ed25519_key"
+
+    c.max_connections = 100
+    c.max_auth_attempts = 6
+
+    c.connection_timeout = 10
+    c.auth_timeout = 30
+    c.inactivity_timeout = 600
+
+    c.keepalive_interval = 30
+    c.keepalive_max = 3
+  end
+end
+```
+
+## Pro Tips
+
+### Development SSH Config
+
+When developing locally, add this to `~/.ssh/config` to avoid `known_hosts` conflicts:
+
+```
+Host localhost
+    UserKnownHostsFile /dev/null
+    StrictHostKeyChecking no
+```
+
+### How It Works
+
+Crussh implements the SSH protocol from scratch using Ruby and a small Rust extension for Poly1305. OpenSSH is never involved — you can uninstall it entirely if you want.
+
+Because there's no default shell behavior, there's no risk of accidentally exposing system access. Your server only does what you explicitly implement.
+
+## Running with systemd
+
+For production deployments, create a systemd unit file:
+
+```ini
+# /etc/systemd/system/myapp.service
+[Unit]
+Description=My SSH App
+After=network.target
+
+[Service]
+Type=simple
+User=myapp
+Group=myapp
+WorkingDirectory=/home/myapp
+ExecStart=/usr/bin/ruby /home/myapp/server.rb
+Restart=on-failure
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Then:
+
+```bash
+# Create a dedicated user
+sudo useradd --system --user-group --create-home myapp
+
+# Enable and start
+sudo systemctl daemon-reload
+sudo systemctl enable myapp
+sudo systemctl start myapp
+```
+
+## Documentation
+
+_Coming soon_
+
+- Getting Started
+- Configuration Reference
+- Authentication Guide
+- Writing Handlers
+- API Reference
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/MSILycanthropy/crussh.
+
+## License
+
+[MIT](LICENSE.txt)
+
+---
+
+Crussh is inspired by [russh](https://github.com/warp-tech/russh) (Rust) and [Wish](https://github.com/charmbracelet/wish) (Go). Built on [Async](https://github.com/socketry/async) for Ruby's concurrent future.

data/lib/crussh/auth.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Crussh
+  module Auth
+    Result = Data.define(:status, :continue_with) do
+      class << self
+        def success
+          new(status: :success, continue_with: nil)
+        end
+
+        def failure
+          new(status: :failure, continue_with: nil)
+        end
+
+        def partial(*methods)
+          new(status: :parital, continue_with: methods)
+        end
+      end
+
+      def success? = status == :success
+      def partial? = status == :partial
+      def failure? = status == :failure
+    end
+
+    class << self
+      def accept = Result.success
+      def reject = Result.failure
+      def partial(...) = Result.partial(...)
+
+      def normalize(result)
+        case result
+        when Result then result
+        when true then accept
+        when false, nil then reject
+        else reject
+        end
+      end
+    end
+
+    module DSL
+      def accept = Auth.accept
+      def reject = Auth.reject
+      def partial(...) = Auth.partial(...)
+    end
+  end
+end

data/lib/crussh/channel/key_parser.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Crussh
+  class Channel
+    module Keys
+      ENTER     = :enter
+      INTERRUPT = :interrupt
+      EOF       = :eof
+      BACKSPACE = :backspace
+      DELETE    = :delete
+      TAB       = :tab
+
+      ARROW_UP    = :arrow_up
+      ARROW_DOWN  = :arrow_down
+      ARROW_LEFT  = :arrow_left
+      ARROW_RIGHT = :arrow_right
+
+      HOME      = :home
+      END_KEY   = :end
+      PAGE_UP   = :page_up
+      PAGE_DOWN = :page_down
+      INSERT    = :insert
+    end
+
+    class KeyParser
+      ESCAPE = "\e"
+      ESCAPE_SEQUENCES = {
+        "[A" => Keys::ARROW_UP,
+        "[B" => Keys::ARROW_DOWN,
+        "[C" => Keys::ARROW_RIGHT,
+        "[D" => Keys::ARROW_LEFT,
+        "[H" => Keys::HOME,
+        "[F" => Keys::END_KEY,
+        "[1~" => Keys::HOME,
+        "[4~" => Keys::END_KEY,
+        "[2~" => Keys::INSERT,
+        "[3~" => Keys::DELETE,
+        "[5~" => Keys::PAGE_UP,
+        "[6~" => Keys::PAGE_DOWN,
+        "OH" => Keys::HOME,
+        "OF" => Keys::END_KEY,
+      }
+      MAX_ESCAPE_LENGTH = 8
+
+      def initialize
+        @escape_buffer = +""
+      end
+
+      def parse(data)
+        keys = []
+
+        data.each_char do |char|
+          if @escape_buffer.empty?
+            if char == ESCAPE
+              @escape_buffer = +ESCAPE
+            else
+              key = parse_char(char)
+              keys << key if key
+            end
+          else
+            @escape_buffer << char
+
+            if complete_escape?
+              key = resolve_escape
+              keys << key if key
+              @escape_buffer = +""
+            elsif @escape_buffer.length >= MAX_ESCAPE_LENGTH
+              @escape_buffer = +""
+            end
+          end
+        end
+
+        keys
+      end
+
+      def flush
+        return if @escape_buffer.empty?
+
+        key = @escape_buffer == ESCAPE ? :escape : nil
+        @escape_buffer = ""
+        key
+      end
+
+      private
+
+      def parse_char(char)
+        case char
+        when "\r", "\n"
+          Keys::ENTER
+        when "\t"
+          Keys::TAB
+        when "\u0003"  # Ctrl+C
+          Keys::INTERRUPT
+        when "\u0004"  # Ctrl+D
+          Keys::EOF
+        when "\u007F", "\b" # DEL and BS
+          Keys::BACKSPACE
+        else
+          char if char.ord >= 32
+        end
+      end
+
+      def complete_escape?
+        return false if @escape_buffer.length < 2
+
+        sequence = @escape_buffer[1..]
+
+        if sequence.start_with?("[")
+          return sequence.length > 1 && sequence[-1].match?(/[A-Za-z~]/)
+        end
+
+        if sequence.start_with?("O")
+          return sequence.length == 2 && sequence[-1].match?(/[A-Za-z]/)
+        end
+
+        sequence >= 2
+      end
+
+      def resolve_escape
+        sequence = @escape_buffer[1..]
+        ESCAPE_SEQUENCES[sequence]
+      end
+    end
+  end
+end