terminalwire 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1240b61fdcc7553eb7d55495ca20b4401c9516641a024a7a59f64ac3fda9144
-  data.tar.gz: 6511112c08684aa011b2026537b8f62c3e7900233f2ea98c4df2f47ccdf2b621
+  metadata.gz: 8eacca5d9e410385fee49a9115cdc9d92ac1276b0666af88b8c343f11306a05f
+  data.tar.gz: c94050aef56399743f202c13c3813bb66a05cfffd2333ea9431bccded43234f2
 SHA512:
-  metadata.gz: 9f5761849e14d51d6491ea7c024769724607081db57968d05abcc25c713dd4afb7808ab4d29873b50c4b2611bcc5e246be3dc7c0bb436fd9ef8c8c4e98e35e10
-  data.tar.gz: f23b101082f1cd1395742ffafffb5c87b5a31d0255153ec5b8c7139cde00a4419575056593a25da6276e33a27b190da2e45b6f3512fa38c7489c4ce98a91a0f3
+  metadata.gz: 2a25a33121a603fdcb11c5c664d17772f999d4a379379390ad578ed434fa75428f45deda6d2023e490ecf2bedfad61cf58a9fd4d7c880e17fff714978075159c
+  data.tar.gz: 76e5bf2edd88ad0ca092328514ebce7bc22ee64ff13aa4ebf83c77319849fe2564515cc89bf27364f3135ca2456143869066ca6eaef70daae15dabedb006b3e3

data/LICENSE.txt

@@ -1 +1 @@
-Copyright (c) 2024 Brad Gessler. Email brad@terminalwire.com to discuss commercial licensing.
+Copyright (c) 2024 Brad Gessler. Email brad@terminalwire.com to discuss licensing.

data/README.md

@@ -1,8 +1,6 @@
 # Terminalwire
 
-TODO: Delete this and the text below, and describe your gem
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/terminalwire`. To experiment with that code, run `bin/console` for an interactive prompt.
+Unlike most command-line tools for web services that require an API, Terminalwire streams terminal I/O between a web server and client over WebSockets. This means you can use your preferred command-line parser within your favorite web server framework to deliver a delightful CLI experience to your users.
 
 ## Installation
 
@@ -14,9 +12,19 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
     $ gem install terminalwire
 
-## Usage
+## Rails
+
+Run the intallation command:
+
+    $ rails g terminalwire:install my-app
+
+This generates the `./bin/my-app` file. Run it to verify that it connects to the server.
+
+    $ bin/my-app
+    Commands:
+      my-app help [COMMAND]  # Describe available commands or one specific command
 
-TODO: Write usage instructions here
+To edit the command-line, open `./app/cli/main_cli.rb` and make changes to the `MainCLI` class.
 
 ## Development
 
@@ -30,7 +38,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/termin
 
 ## License
 
-The gem is available as a propietary license. Email brad@terminalwire.com to discuss commercial licensing.
+The gem is available as a propietary license. Email brad@terminalwire.com to discuss licensing.
 
 ## Code of Conduct
 

data/examples/exec/localrails

@@ -0,0 +1,2 @@
+#!/usr/bin/env terminalwire-exec
+url: "ws://localhost:3000/terminal"

data/exe/terminalwire-exec

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+require_relative "../lib/terminalwire.rb"
+
+begin
+  Terminalwire::Client::Exec.start
+rescue Terminalwire::Error => e
+  puts e.message
+  exit 1
+end

data/lib/generators/terminalwire/install/USAGE

@@ -0,0 +1,9 @@
+Description:
+    Installs Terminalwire
+
+Example:
+    bin/rails generate terminalwire:install
+
+    This will create:
+        app/terminal/application_terminal.rb
+        bin/<your-app>

data/lib/generators/terminalwire/install/install_generator.rb

@@ -0,0 +1,37 @@
+require "bundler"
+
+class Terminalwire::InstallGenerator < Rails::Generators::Base
+  source_root File.expand_path("templates", __dir__)
+
+  argument :binary_name, type: :string, required: true, banner: "binary_name"
+
+  def create_terminal_files
+    template "application_terminal.rb.tt", Rails.root.join("app/terminal/application_terminal.rb")
+  end
+
+  def create_binary_files
+    copy_file "bin/terminalwire", binary_path
+    chmod binary_path, 0755, verbose: false
+  end
+
+  def add_route
+    route <<~ROUTE
+      match "/terminal",
+        to: Terminalwire::Server::Thor.new(ApplicationTerminal),
+        via: [:get, :connect]
+    ROUTE
+  end
+
+  def print_post_install_message
+    say ""
+    say "Terminalwire has been successfully installed!", :green
+    say "Run `#{binary_path.relative_path_from(Rails.root)}` to verify everything is in working order. For support visit https://terminalwire.com."
+    say ""
+  end
+
+  private
+
+  def binary_path
+    Rails.root.join("bin", binary_name)
+  end
+end

data/lib/generators/terminalwire/install/templates/application_terminal.rb.tt

@@ -0,0 +1,54 @@
+# Learn how to use Thor at http://whatisthor.com.
+class ApplicationTerminal < Thor
+  include Terminalwire::Thor
+
+  def self.basename = "<%= binary_name %>"
+
+  desc "hello NAME", "say hello to NAME"
+  def hello(name)
+    puts "Hello #{name}"
+  end
+
+  desc "login", "Login to your account"
+  def login
+    print "Email: "
+    email = gets
+
+    print "Password: "
+    password = getpass
+
+    if self.current_user = User.authenticate(email, password)
+      puts "Successfully logged in as #{user.email}."
+    else
+      puts "Could not find a user with that email and password."
+    end
+  end
+
+  desc "whoami", "Displays current user information."
+  def whoami
+    if self.current_user
+      puts "Logged in as #{user.email}."
+    else
+      puts "Not logged in. Run `#{self.class.basename} login` to login."
+    end
+  end
+
+  desc "logout", "Logout of your account"
+  def logout
+    session.reset
+    puts "Successfully logged out."
+  end
+
+  private
+
+  def current_user=(user)
+    # The Session object is a hash-like object that encrypts and signs a hash that's
+    # stored on the client's file sytem. Conceptually, it's similar to Rails signed
+    # and encrypted client-side cookies.
+    session["user_id"] = user.id
+  end
+
+  def current_user
+    @current_user ||= User.find(session.fetch("user_id"))
+  end
+end

data/lib/generators/terminalwire/install/templates/bin/terminalwire

@@ -0,0 +1,2 @@
+#!/usr/bin/env terminalwire-exec
+url: "ws://localhost:3000/terminal"

data/lib/terminalwire/adapter.rb

@@ -0,0 +1,32 @@
+require 'msgpack'
+
+module Terminalwire
+  class Adapter
+    include Logging
+
+    attr_reader :transport
+
+    def initialize(transport)
+      @transport = transport
+    end
+
+    def write(data)
+      logger.debug "Adapter: Sending #{data.inspect}"
+      packed_data = MessagePack.pack(data, symbolize_keys: true)
+      @transport.write(packed_data)
+    end
+
+    def recv
+      logger.debug "Adapter: Reading"
+      packed_data = @transport.read
+      return nil if packed_data.nil?
+      data = MessagePack.unpack(packed_data, symbolize_keys: true)
+      logger.debug "Adapter: Received #{data.inspect}"
+      data
+    end
+
+    def close
+      @transport.close
+    end
+  end
+end

data/lib/terminalwire/client/entitlement.rb

@@ -0,0 +1,107 @@
+module Terminalwire::Client
+  class Entitlement
+    class Paths
+      include Enumerable
+
+      def initialize
+        @permitted = []
+      end
+
+      def each(&)
+        @permitted.each(&)
+      end
+
+      def permit(path)
+        @permitted.append Pathname.new(path).expand_path
+      end
+
+      def permitted?(path)
+        @permitted.find { |pattern| matches?(permitted: pattern, path:) }
+      end
+
+      def serialize
+        @permitted.to_a.map(&:to_s)
+      end
+
+      private
+      def matches?(permitted:, path:)
+        # This MUST be done via File.fnmatch because Pathname#fnmatch does not work. If you
+        # try changing this 🚨 YOU MAY CIRCUMVENT THE SECURITY MEASURES IN PLACE. 🚨
+        File.fnmatch permitted.to_s, File.expand_path(path), File::FNM_PATHNAME
+      end
+    end
+
+    class Schemes
+      include Enumerable
+
+      def initialize
+        @permitted = Set.new
+      end
+
+      def each(&)
+        @permitted.each(&)
+      end
+
+      def permit(scheme)
+        @permitted << scheme.to_s
+      end
+
+      def permitted?(url)
+        include? URI(url).scheme
+      end
+
+      def serialize
+        @permitted.to_a.map(&:to_s)
+      end
+    end
+
+    attr_reader :paths, :authority, :schemes
+
+    def initialize(authority:)
+      @authority = authority
+      @paths = Paths.new
+
+      # Permit the domain directory. This is necessary for basic operation of the client.
+      @paths.permit storage_path
+      @paths.permit storage_pattern
+
+      @schemes = Schemes.new
+      # Permit http & https by default.
+      @schemes.permit "http"
+      @schemes.permit "https"
+    end
+
+    def domain_path
+      Pathname.new("~/.terminalwire/authorities/#{@authority}").expand_path
+    end
+
+    def storage_path
+      domain_path.join("storage")
+    end
+
+    def storage_pattern
+      storage_path.join("**/*")
+    end
+
+    def serialize
+      {
+        authority: @authority,
+        schemes: @schemes.serialize,
+        paths: @paths.serialize,
+        storage_path: storage_path.to_s,
+      }
+    end
+
+    def self.from_url(url)
+      # I had to lift this from URI::HTTP because `ws://` doesn't
+      # have an authority method.
+      authority = if url.port == url.default_port
+        url.host
+      else
+        "#{url.host}:#{url.port}"
+      end
+
+      new authority:
+    end
+  end
+end

data/lib/terminalwire/client/exec.rb

@@ -0,0 +1,35 @@
+require "pathname"
+require "yaml"
+require "uri"
+
+module Terminalwire::Client
+  class Exec
+    attr_reader :arguments, :path, :configuration, :url
+
+    def initialize(path:, arguments:)
+      @arguments = arguments
+      @path = Pathname.new(path)
+      @configuration = YAML.load_file(@path)
+      @url = URI(@configuration.fetch("url"))
+    rescue Errno::ENOENT => e
+      raise Terminalwire::Error, "File not found: #{@path}"
+    rescue URI::InvalidURIError => e
+      raise Terminalwire::Error, "Invalid URI: #{@url}"
+    rescue KeyError => e
+      raise Terminalwire::Error, "Missing key in configuration: #{e}"
+    end
+
+    def start
+      Terminalwire::Client.websocket(url:, arguments:)
+    end
+
+    def self.start
+      case ARGV
+      in path, *arguments
+        new(path:, arguments:).start
+      end
+    rescue NoMatchingPatternError => e
+      raise Terminalwire::Error, "Launched with incorrect arguments: #{ARGV}"
+    end
+  end
+end

data/lib/terminalwire/client/resource.rb

@@ -0,0 +1,154 @@
+module Terminalwire::Client::Resource
+  # Dispatches messages from the Client::Handler to the appropriate resource.
+  class Handler
+    include Enumerable
+
+    def initialize
+      @resources = {}
+      yield self if block_given?
+    end
+
+    def each(&block)
+      @resources.values.each(&block)
+    end
+
+    def add(resource)
+      # Detect if the resource is already registered and throw an error
+      if @resources.key?(resource.name)
+        raise "Resource #{resource.name} already registered"
+      else
+        @resources[resource.name] = resource
+      end
+    end
+    alias :<< :add
+
+    def dispatch(**message)
+      case message
+      in { event:, action:, name:, command:, parameters: }
+        resource = @resources.fetch(name)
+        resource.command(command, **parameters)
+      end
+    end
+  end
+
+  # Dispatcher, security, and response macros for resources.
+  class Base < Terminalwire::Resource::Base
+    def initialize(*, entitlement:, **)
+      super(*, **)
+      @entitlement = entitlement
+      connect
+    end
+
+    def command(command, **parameters)
+      begin
+        if permit(command, **parameters)
+          succeed self.public_send(command, **parameters)
+        else
+          fail "Client denied #{command}", command:, parameters:
+        end
+      rescue => e
+        fail e.message, command:, parameters:
+        raise
+      end
+    end
+
+    def permit(...)
+      false
+    end
+  end
+
+  class STDOUT < Base
+    def connect
+      @io = $stdout
+    end
+
+    def print(data:)
+      @io.print(data)
+    end
+
+    def print_line(data:)
+      @io.puts(data)
+    end
+
+    def permit(...)
+      true
+    end
+  end
+
+  class STDERR < STDOUT
+    def connect
+      @io = $stderr
+    end
+  end
+
+  class STDIN < Base
+    def connect
+      @io = $stdin
+    end
+
+    def read_line
+      @io.gets
+    end
+
+    def read_password
+      @io.getpass
+    end
+
+    def permit(...)
+      true
+    end
+  end
+
+  class File < Base
+    File = ::File
+
+    # Ensure the default file mode is read/write for owner only. This ensures
+    # that if the server tries uploading an executable file, it won't be when it
+    # lands on the client.
+    #
+    # Eventually we'll move this into entitlements so the client can set maximum
+    # permissions for files and directories.
+    FILE_PERMISSIONS = 0o600 # rw-------
+
+    def read(path:)
+      File.read File.expand_path(path)
+    end
+
+    def write(path:, content:)
+      File.open(File.expand_path(path), "w", FILE_PERMISSIONS) { |f| f.write(content) }
+    end
+
+    def append(path:, content:)
+      File.open(File.expand_path(path), "a", FILE_PERMISSIONS) { |f| f.write(content) }
+    end
+
+    def mkdir(path:)
+      FileUtils.mkdir_p(File.expand_path(path))
+    end
+
+    def delete(path:)
+      File.delete(File.expand_path(path))
+    end
+
+    def exist(path:)
+      File.exist? File.expand_path(path)
+    end
+
+    def permit(command, path:, **)
+      @entitlement.paths.permitted? path
+    end
+  end
+
+  class Browser < Base
+    def permit(command, url:, **)
+      @entitlement.schemes.permitted? url
+    end
+
+    def launch(url:)
+      Launchy.open(URI(url))
+      # TODO: This is a hack to get the `respond` method to work.
+      # Maybe explicitly call a `suceed` and `fail` method?
+      nil
+    end
+  end
+end

data/lib/terminalwire/client.rb

@@ -0,0 +1,91 @@
+require 'fileutils'
+require 'launchy'
+require 'io/console'
+
+module Terminalwire
+  module Client
+    class Handler
+      VERSION = "0.1.0".freeze
+
+      include Logging
+
+      attr_reader :adapter, :entitlement, :resources
+
+      def initialize(adapter, arguments: ARGV, program_name: $0, entitlement:)
+        @entitlement = entitlement
+        @adapter = adapter
+        @program_arguments = arguments
+        @program_name = program_name
+
+        @resources = Resource::Handler.new do |it|
+          it << Resource::STDOUT.new("stdout", @adapter, entitlement:)
+          it << Resource::STDIN.new("stdin", @adapter, entitlement:)
+          it << Resource::STDERR.new("stderr", @adapter, entitlement:)
+          it << Resource::Browser.new("browser", @adapter, entitlement:)
+          it << Resource::File.new("file", @adapter, entitlement:)
+        end
+      end
+
+      def connect
+        @adapter.write(event: "initialization",
+         protocol: { version: VERSION },
+         entitlement: @entitlement.serialize,
+         program: {
+           name: @program_name,
+           arguments: @program_arguments
+         })
+
+        loop do
+          handle @adapter.recv
+        end
+      end
+
+      def handle(message)
+        case message
+        in { event: "resource", action: "command", name:, parameters: }
+          @resources.dispatch(**message)
+        in { event: "exit", status: }
+          exit Integer(status)
+        end
+      end
+    end
+
+    def self.tcp(...)
+      socket = TCPSocket.new(...)
+      transport = Terminalwire::Transport::Socket.new(socket)
+      adapter = Terminalwire::Adapter.new(transport)
+      Terminalwire::Client::Handler.new(adapter)
+    end
+
+    def self.socket(...)
+      socket = UNIXSocket.new(...)
+      transport = Terminalwire::Transport::Socket.new(socket)
+      adapter = Terminalwire::Adapter.new(transport)
+      Terminalwire::Client::Handler.new(adapter)
+    end
+
+    # Extracted from HTTP. This is so we can
+    def self.authority(url)
+      if url.port == url.default_port
+        url.host
+      else
+        "#{url.host}:#{url.port}"
+      end
+    end
+
+    def self.websocket(url:, arguments: ARGV)
+      url = URI(url)
+
+      Async do |task|
+        endpoint = Async::HTTP::Endpoint.parse(url)
+
+        Async::WebSocket::Client.connect(endpoint) do |adapter|
+          transport = Terminalwire::Transport::WebSocket.new(adapter)
+          adapter = Terminalwire::Adapter.new(transport)
+          entitlement = Entitlement.from_url(url)
+          Terminalwire::Client::Handler.new(adapter, arguments:, entitlement:).connect
+        end
+      end
+    end
+  end
+end

data/lib/terminalwire/logging.rb

@@ -0,0 +1,8 @@
+require 'logger'
+
+module Terminalwire
+  module Logging
+    DEVICE = Logger.new($stdout, level: ENV.fetch("LOG_LEVEL", "info"))
+    def logger = DEVICE
+  end
+end

data/lib/terminalwire/rails.rb

@@ -0,0 +1,69 @@
+require 'jwt'
+require 'pathname'
+require 'forwardable'
+
+module Terminalwire::Rails
+  class Session
+    # JWT file name for the session file.
+    FILENAME = "session.jwt"
+
+    # Empty dictionary the user can stash all their session data into.
+    EMPTY_SESSION = {}.freeze
+
+    extend Forwardable
+
+    # Delegate `dig` and `fetch` to the `read` method
+    def_delegators :read,
+      :dig, :fetch, :[]
+
+    def initialize(context:, path: nil, secret_key: self.class.secret_key)
+      @context = context
+      @path = path || context.storage_path
+      @config_file_path = @path.join(FILENAME)
+      @secret_key = secret_key
+
+      ensure_file
+    end
+
+    def read
+      jwt_token = @context.file.read(@config_file_path)
+      decoded_data = JWT.decode(jwt_token, @secret_key, true, algorithm: 'HS256')
+      decoded_data[0]  # JWT payload is the first element in the array
+    rescue JWT::DecodeError => e
+      raise "Invalid or tampered file: #{e.message}"
+    end
+
+    def reset
+      @context.file.delete @config_file_path
+    end
+
+    def edit
+      config = read
+      yield config
+      write(config)
+    end
+
+    def []=(key, value)
+      edit { |config| config[key] = value }
+    end
+
+    def write(config)
+      token = JWT.encode(config, @secret_key, 'HS256')
+      @context.file.write(@config_file_path, token)
+    end
+
+    private
+
+    def ensure_file
+      return true if @context.file.exist? @config_file_path
+      # Create the path if it doesn't exist on the client.
+      @context.file.mkdir(@path) unless @context.file.exist?(@path)
+      # Write an empty configuration on initialization
+      write(EMPTY_SESSION)
+    end
+
+    def self.secret_key
+      Rails.application.secret_key_base
+    end
+  end
+end