terminalwire-client 0.3.0.alpha1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 60d8965eb9d76fbfe435e72747553489817c77e2a82fa5cdba7933d6c7798c21
+  data.tar.gz: 611a958e01b7216ebb23dd311db799f84bc76cfcda5b7c6dcecaaaf71959ed0e
+SHA512:
+  metadata.gz: 1f9c42e92bc39458fd0ba4c3ea09fa5a240444f3a2e368ebe1aa62819b85dbe20037cadb3331d628737ed40e5e2300cbde5260a201571046b00a7cbf87e445b6
+  data.tar.gz: 5277aa2111746a0c19e25b4dcef9a1e51cb941e0efbd6ce408957e5166257da051cebc13920f3cb92039d2db43bf361c3529f98110ac5f74945c8a046debe8c8

data/lib/terminalwire/client/entitlement/environment_variables.rb

@@ -0,0 +1,26 @@
+module Terminalwire::Client::Entitlement
+  # ENV vars that the server can access on the client.
+  class EnvironmentVariables
+    include Enumerable
+
+    def initialize
+      @permitted = Set.new
+    end
+
+    def each(&)
+      @permitted.each(&)
+    end
+
+    def permit(variable)
+      @permitted << variable.to_s
+    end
+
+    def permitted?(key)
+      include? key.to_s
+    end
+
+    def serialize
+      map { |name| { name: } }
+    end
+  end
+end

data/lib/terminalwire/client/entitlement/paths.rb

@@ -0,0 +1,97 @@
+module Terminalwire::Client::Entitlement
+  # A list of paths and permissions that server has to write on the client workstation.
+  class Paths
+    class Permit
+      attr_reader :path, :mode
+      # 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.
+      MODE = 0o600 # rw-------
+
+      # Constants for permission bit masks
+      OWNER_PERMISSIONS = 0o700 # rwx------
+      GROUP_PERMISSIONS = 0o070 # ---rwx---
+      OTHERS_PERMISSIONS = 0o007 # ------rwx
+
+      # We'll validate that modes are within this range.
+      MODE_RANGE = 0o000..0o777
+
+      def initialize(path:, mode: MODE)
+        @path = Pathname.new(path)
+        @mode = convert(mode)
+      end
+
+      def permitted_path?(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 @path.to_s, path.to_s, File::FNM_PATHNAME
+      end
+
+      def permitted_mode?(value)
+        # Ensure the mode is at least as permissive as the permitted mode.
+        mode = convert(value)
+
+        # Extract permission bits for owner, group, and others
+        owner_bits = mode & OWNER_PERMISSIONS
+        group_bits = mode & GROUP_PERMISSIONS
+        others_bits = mode & OTHERS_PERMISSIONS
+
+        # Ensure that the mode doesn't grant more permissions than @mode in any class (owner, group, others)
+        (owner_bits <= @mode & OWNER_PERMISSIONS) &&
+        (group_bits <= @mode & GROUP_PERMISSIONS) &&
+        (others_bits <= @mode & OTHERS_PERMISSIONS)
+      end
+
+      def permitted?(path:, mode: @mode)
+        permitted_path?(path) && permitted_mode?(mode)
+      end
+
+      def serialize
+        {
+          location: @path.to_s,
+          mode: @mode
+        }
+      end
+
+      protected
+      def convert(value)
+        mode = Integer(value)
+        raise ArgumentError, "The mode #{format_octet value} must be an octet value between #{format_octet MODE_RANGE.first} and #{format_octet MODE_RANGE.last}" unless MODE_RANGE.cover?(mode)
+        mode
+      end
+
+      def format_octet(value)
+        format("0o%03o", value)
+      end
+    end
+
+    include Enumerable
+
+    def initialize
+      @permitted = []
+    end
+
+    def each(&)
+      @permitted.each(&)
+    end
+
+    def permit(path, **)
+      @permitted.append Permit.new(path:, **)
+    end
+
+    def permitted?(path, mode: nil)
+      if mode
+        find { |it| it.permitted_path?(path) and it.permitted_mode?(mode) }
+      else
+        find { |it| it.permitted_path?(path) }
+      end
+    end
+
+    def serialize
+      map(&:serialize)
+    end
+  end
+end

data/lib/terminalwire/client/entitlement/policy.rb

@@ -0,0 +1,117 @@
+module Terminalwire::Client::Entitlement
+  module Policy
+    # A policy has the authority, paths, and schemes that the server is allowed to access.
+    class Base
+      attr_reader :paths, :authority, :schemes, :environment_variables
+
+      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"
+
+        @environment_variables = EnvironmentVariables.new
+        # Permit the HOME and TERMINALWIRE_HOME environment variables.
+        @environment_variables.permit "TERMINALWIRE_HOME"
+      end
+
+      def root_path
+        # TODO: This needs to be passed into the Policy so that it can be set by the client.
+        Terminalwire::Client.root_path
+      end
+
+      def authority_path
+        root_path.join("authorities/#{authority}")
+      end
+
+      def storage_path
+        authority_path.join("storage")
+      end
+
+      def storage_pattern
+        storage_path.join("**/*")
+      end
+
+      def serialize
+        {
+          authority: @authority,
+          schemes: @schemes.serialize,
+          paths: @paths.serialize,
+          environment_variables: @environment_variables.serialize
+        }
+      end
+    end
+
+    class Root < Base
+      AUTHORITY = "terminalwire.com".freeze
+
+      # Terminalwire checks these to install the binary stubs path.
+      SHELL_INITIALIZATION_FILE_PATHS = %w[
+        ~/.bash_profile
+        ~/.bashrc
+        ~/.zprofile
+        ~/.zshrc
+        ~/.profile
+        ~/.config/fish/config.fish
+        ~/.bash_login
+        ~/.cshrc
+        ~/.tcshrc
+      ].freeze
+
+      # Ensure the binary stubs are executable. This increases the
+      # file mode entitlement so that stubs created in ./bin are executable.
+      BINARY_PATH_FILE_MODE = 0o755
+
+      def initialize(*, **, &)
+        # Make damn sure the authority is set to Terminalwire.
+        super(*, authority: AUTHORITY, **, &)
+
+        # Now setup special permitted paths.
+        @paths.permit root_path
+        @paths.permit root_pattern
+        # Permit the dotfiles so terminalwire can install the binary stubs.
+        SHELL_INITIALIZATION_FILE_PATHS.each do |path|
+          @paths.permit path
+        end
+
+        # Permit terminalwire to grant execute permissions to the binary stubs.
+        @paths.permit binary_pattern, mode: BINARY_PATH_FILE_MODE
+
+        # Used to check if terminalwire is setup in the user's PATH environment variable.
+        @environment_variables.permit "PATH"
+      end
+
+      # Grant access to the `~/.terminalwire/**/*` path so users can install
+      # terminalwire apps via `terminalwire install svbtle`, etc.
+      def root_pattern
+        root_path.join("**/*").freeze
+      end
+
+      # Path where the terminalwire binary stubs are stored.
+      def binary_path
+        root_path.join("bin").freeze
+      end
+
+      # Pattern for the binary path.
+      def binary_pattern
+        binary_path.join("*").freeze
+      end
+    end
+
+    def self.resolve(*, authority:, **, &)
+      case authority
+      when Policy::Root::AUTHORITY
+        Root.new(*, **, &)
+      else
+        Base.new *, authority:, **, &
+      end
+    end
+  end
+end

data/lib/terminalwire/client/entitlement/schemes.rb

@@ -0,0 +1,26 @@
+module Terminalwire::Client::Entitlement
+  # URLs the server can open on the client.
+  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
+      map { |scheme| { scheme: } }
+    end
+  end
+end

data/lib/terminalwire/client/entitlement.rb

@@ -0,0 +1,9 @@
+require "pathname"
+
+module Terminalwire::Client
+  # Entitlements are the security boundary between the server and the client that lives on the client.
+  # The server might request a file or directory from the client, and the client will check the entitlements
+  # to see if the server is authorized to access the requested resource.
+  module Entitlement
+  end
+end

data/lib/terminalwire/client/exec.rb

@@ -0,0 +1,44 @@
+require "pathname"
+require "yaml"
+require "uri"
+
+module Terminalwire::Client
+  # Called by the `terminalwire-exec` shebang in scripts. This makes it easy for people
+  # to create their own scripts that use Terminalwire that look like this:
+  #
+  # ```sh
+  # #!/usr/bin/env terminalwire-exec
+  # url: "https://terminalwire.com/terminal"
+  # ```
+  #
+  # These files are saved, then `chmod + x` is run on them and they become executable.
+  class Exec
+    attr_reader :arguments, :path, :configuration, :url
+
+    def initialize(path:, arguments:)
+      @arguments = arguments
+      @path = Pathname.new(path)
+      @configuration = YAML.safe_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/handler.rb

@@ -0,0 +1,67 @@
+module Terminalwire::Client
+  # The handler is the main class that connects to the Terminalwire server and
+  # dispatches messages to the appropriate resources.
+  class Handler
+    VERSION = "0.1.0".freeze
+
+    include Terminalwire::Logging
+
+    attr_reader :adapter, :resources, :endpoint
+    attr_accessor :entitlement
+
+    def initialize(adapter, arguments: ARGV, program_name: $0, endpoint:)
+      @endpoint = endpoint
+      @adapter = adapter
+      @program_arguments = arguments
+      @program_name = program_name
+      @entitlement = Entitlement::Policy.resolve(authority: @endpoint.authority)
+
+      yield self if block_given?
+
+      @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:)
+        it << Resource::Directory.new("directory", @adapter, entitlement:)
+        it << Resource::EnvironmentVariable.new("environment_variable", @adapter, entitlement:)
+      end
+    end
+
+    def verify_license
+      # Connect to the Terminalwire license server to verify the URL endpoint
+      # and displays a message to the user, if any are present.
+      $stdout.print ServerLicenseVerification.new(url: @endpoint.to_url).message
+    rescue
+      $stderr.puts "Failed to verify server license."
+    end
+
+    def connect
+      verify_license
+
+      @adapter.write(
+        event: "initialization",
+        protocol: { version: VERSION },
+        entitlement: @entitlement.serialize,
+        program: {
+          name: @program_name,
+          arguments: @program_arguments
+        }
+      )
+
+      loop do
+        handle @adapter.read
+      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
+end

data/lib/terminalwire/client/resource.rb

@@ -0,0 +1,204 @@
+require "fileutils"
+require "io/console"
+
+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
+
+    protected
+
+    def permit(...)
+      false
+    end
+  end
+
+  class EnvironmentVariable < Base
+    # Accepts a list of environment variables to permit.
+    def read(name:)
+      ENV[name]
+    end
+
+    # def write(name:, value:)
+    #   ENV[name] = value
+    # end
+
+    protected
+
+    def permit(command, name:, **)
+      @entitlement.environment_variables.permitted? name
+    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
+
+    protected
+
+    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
+
+    protected
+
+    def permit(...)
+      true
+    end
+  end
+
+  class File < Base
+    File = ::File
+
+    def read(path:)
+      File.read File.expand_path(path)
+    end
+
+    def write(path:, content:, mode: nil)
+      File.open(File.expand_path(path), "w", mode) { |f| f.write(content) }
+    end
+
+    def append(path:, content:, mode: nil)
+      File.open(File.expand_path(path), "a", mode) { |f| f.write(content) }
+    end
+
+    def delete(path:)
+      File.delete File.expand_path(path)
+    end
+
+    def exist(path:)
+      File.exist? File.expand_path(path)
+    end
+
+    def change_mode(path:, mode:)
+      File.chmod mode, File.expand_path(path)
+    end
+
+    protected
+
+    def permit(command, path:, mode: nil, **)
+      @entitlement.paths.permitted? path, mode:
+    end
+  end
+
+  class Directory < Base
+    File = ::File
+
+    def list(path:)
+      Dir.glob path
+    end
+
+    def create(path:)
+      FileUtils.mkdir_p File.expand_path(path)
+    rescue Errno::EEXIST
+      # Do nothing
+    end
+
+    def exist(path:)
+      Dir.exist? path
+    end
+
+    def delete(path:)
+      Dir.delete path
+    end
+
+    protected
+
+    def permit(command, path:, **)
+      @entitlement.paths.permitted? path
+    end
+  end
+
+  class Browser < Base
+    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
+
+    protected
+
+    def permit(command, url:, **)
+      @entitlement.schemes.permitted? url
+    end
+  end
+end

data/lib/terminalwire/client/server_license_verification.rb

@@ -0,0 +1,74 @@
+require "async/http/internet"
+require "base64"
+require "uri"
+require "fileutils"
+
+module Terminalwire::Client
+  # Checkes the server for a license verification at `https://terminalwire.com/licenses/verifications/`
+  # and displays the message to the user, if necessary.
+  class ServerLicenseVerification
+    include Terminalwire::Logging
+
+    def initialize(url:)
+      @url = URI(url)
+      @internet = Async::HTTP::Internet.new
+      @cache_store = Terminalwire::Cache::File::Store.new(path: Terminalwire::Client.root_path.join("cache/licenses/verifications"))
+    end
+
+    def key
+      Base64.urlsafe_encode64 @url
+    end
+
+    def cache = @cache_store.entry key
+
+    def payload
+      if cache.miss?
+        logger.debug "Stale verification. Requesting new verification."
+        request do |response|
+          # Set the expiry on the file cache for the header.
+          if max_age = response.headers["cache-control"].max_age
+            logger.debug "Caching for #{max_age}"
+            cache.expires = Time.now + max_age
+          end
+
+          # Process based on the response code.
+          case response.status
+          in 200
+            logger.debug "License for #{@url} found."
+            data = self.class.unpack response.read
+            cache.value = data
+            return data
+          in 404
+            logger.debug "License for #{@url} not found."
+            return self.class.unpack response.read
+          end
+        end
+      else
+        return cache.value
+      end
+    end
+
+    def message
+      payload.dig(:shell, :output)
+    end
+
+    protected
+
+    def verification_url
+      Terminalwire.url
+        .path("/licenses/verifications", key)
+    end
+
+    def request(&)
+      logger.debug "Requesting license verification from #{verification_url}."
+      response = @internet.get verification_url, {
+        "Accept" => "application/x-msgpack",
+        "User-Agent" => "Terminalwire/#{Terminalwire::VERSION} Ruby/#{RUBY_VERSION} (#{RUBY_PLATFORM})",
+      }, &
+    end
+
+    def self.unpack(pack)
+      MessagePack.unpack(pack, symbolize_keys: true)
+    end
+  end
+end

data/lib/terminalwire/client.rb

@@ -0,0 +1,45 @@
+require 'terminalwire'
+
+require 'launchy'
+require 'io/console'
+require 'pathname'
+
+require 'forwardable'
+require 'uri'
+
+require 'async'
+require 'async/http/endpoint'
+require 'async/websocket/client'
+require 'async/websocket/adapters/rack'
+require 'uri-builder'
+
+require "zeitwerk"
+Zeitwerk::Loader.for_gem_extension(Terminalwire).tap do |loader|
+  loader.setup
+end
+
+module Terminalwire
+  module Client
+    ROOT_PATH = "~/.terminalwire".freeze
+    def self.root_path = Pathname.new(ENV.fetch("TERMINALWIRE_HOME", ROOT_PATH))
+
+    def self.websocket(url:, arguments: ARGV, &configuration)
+      ENV["TERMINALWIRE_HOME"] ||= root_path.to_s
+
+      url = URI(url)
+
+      Async do |task|
+        endpoint = Async::HTTP::Endpoint.parse(
+          url,
+          alpn_protocols: Async::HTTP::Protocol::HTTP11.names
+        )
+
+        Async::WebSocket::Client.connect(endpoint) do |adapter|
+          transport = Terminalwire::Transport::WebSocket.new(adapter)
+          adapter = Terminalwire::Adapter::Socket.new(transport)
+          Terminalwire::Client::Handler.new(adapter, arguments:, endpoint:, &configuration).connect
+        end
+      end
+    end
+  end
+end

data/lib/terminalwire-client.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'terminalwire/client'

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: terminalwire-client
+version: !ruby/object:Gem::Version
+  version: 0.3.0.alpha1
+platform: ruby
+authors:
+- Brad Gessler
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-12-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: launchy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: terminalwire-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.3.0.alpha1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.3.0.alpha1
+description: Stream command-line apps from your server without a web API
+email:
+- brad@terminalwire.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/terminalwire-client.rb
+- lib/terminalwire/client.rb
+- lib/terminalwire/client/entitlement.rb
+- lib/terminalwire/client/entitlement/environment_variables.rb
+- lib/terminalwire/client/entitlement/paths.rb
+- lib/terminalwire/client/entitlement/policy.rb
+- lib/terminalwire/client/entitlement/schemes.rb
+- lib/terminalwire/client/exec.rb
+- lib/terminalwire/client/handler.rb
+- lib/terminalwire/client/resource.rb
+- lib/terminalwire/client/server_license_verification.rb
+homepage: https://terminalwire.com/ruby
+licenses:
+- Proprietary (https://terminalwire.com/license)
+metadata:
+  allowed_push_host: https://rubygems.org/
+  homepage_uri: https://terminalwire.com/ruby
+  source_code_uri: https://github.com/terminalwire/ruby/tree/main/terminalwire-client
+  changelog_uri: https://github.com/terminalwire/ruby/tags
+  funding_uri: https://terminalwire.com/funding
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.9
+signing_key:
+specification_version: 4
+summary: Ship a CLI for your web app. No API required.
+test_files: []