terminalwire 0.1.7 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8bd8279b508f75e2d707b7dc94d58321694f3920de9781b65e45f44e3c83595e
-  data.tar.gz: 9899e73daed242f8516a03c419f5c07c6f675399fff147125dca99d4515f847a
+  metadata.gz: 021c12812432f96320c0ba322f4aa71e1b1cfb60c52b77bc6cd78013da78c517
+  data.tar.gz: b5f13d773a7c7bc4d7f5e358c2fb0d498a9061fb6cb191f9ab55bc6fe3131767
 SHA512:
-  metadata.gz: 9136ff6080599802796f2b96089785341128b3a2c814eb53527d47c993b7f21da000a716f4b7aad920bd2da91ff06bb88c34170db83636218d6b7351e2a7ce6d
-  data.tar.gz: 114660aa187d13544186409f6b65c9ff2ff429050ab9df49c70440b326c0f1961b30571e81227cc8b44d9c23059915c93ef0bf821ef77eea150100da57542d3b
+  metadata.gz: f3206e529d8628243061e87cf4b1782e4d61a368333627e2526f5e251e25daefec1f8a4e24fb71e85c5aa3f1114138eb99100877c029668913fc93230d626eaa
+  data.tar.gz: c5ae063fc7eb0f17fe6a6da9b18d79cf5f5c039262849bbb24bc33add9276294f78335a262247c86cab2a8667494de9411532f4bcd983425cdeecc3e5d51d83e

data/lib/terminalwire/adapter.rb

@@ -1,8 +1,9 @@
 require 'msgpack'
 
-module Terminalwire
-  class Adapter
-    include Logging
+module Terminalwire::Adapter
+  # Works with TCP, Unix, WebSocket, and other socket-like abstractions.
+  class Socket
+    include Terminalwire::Logging
 
     attr_reader :transport
 
@@ -29,4 +30,24 @@ module Terminalwire
       @transport.close
     end
   end
+
+  # This is a test adapter that can be used for testing purposes.
+  class Test
+    attr_reader :responses
+
+    def initialize(responses = [])
+      @responses = responses
+    end
+
+    def write(**data)
+      @responses << data
+    end
+
+    def response
+      @responses.pop
+    end
+
+    def close
+    end
+  end
 end

data/lib/terminalwire/client/entitlement.rb

@@ -3,6 +3,73 @@ require "pathname"
 module Terminalwire::Client
   module Entitlement
     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).expand_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, File.expand_path(path), 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
@@ -13,23 +80,20 @@ module Terminalwire::Client
         @permitted.each(&)
       end
 
-      def permit(path)
-        @permitted.append Pathname.new(path).expand_path
+      def permit(path, **)
+        @permitted.append Permit.new(path:, **)
       end
 
-      def permitted?(path)
-        @permitted.find { |pattern| matches?(permitted: pattern, path:) }
+      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
-        @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
+        map(&:serialize)
       end
     end
 
@@ -105,6 +169,10 @@ module Terminalwire::Client
     class RootPolicy < Policy
       HOST = "terminalwire.com".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: HOST, **, &)
@@ -112,6 +180,9 @@ module Terminalwire::Client
         # Now setup special permitted paths.
         @paths.permit root_path
         @paths.permit root_pattern
+
+        # Permit terminalwire to grant execute permissions to the binary stubs.
+        @paths.permit binary_pattern, mode: BINARY_PATH_FILE_MODE
       end
 
       # Grant access to the `~/.terminalwire/**/*` path so users can install
@@ -119,6 +190,16 @@ module Terminalwire::Client
       def root_pattern
         root_path.join("**/*")
       end
+
+      # Path where the terminalwire binary stubs are stored.
+      def binary_path
+        root_path.join("bin")
+      end
+
+      # Pattern for the binary path.
+      def binary_pattern
+        binary_path.join("*")
+      end
     end
 
     def self.from_url(url)

data/lib/terminalwire/client/resource.rb

@@ -102,28 +102,16 @@ module Terminalwire::Client::Resource
   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) }
+    def write(path:, content:, mode: nil)
+      File.open(File.expand_path(path), "w", mode) { |f| f.write(content) }
     end
 
-    def mkdir(path:)
-      FileUtils.mkdir_p(File.expand_path(path))
+    def append(path:, content:, mode: nil)
+      File.open(File.expand_path(path), "a", mode) { |f| f.write(content) }
     end
 
     def delete(path:)
@@ -134,6 +122,37 @@ module Terminalwire::Client::Resource
       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(File.expand_path(path))
+    end
+
+    def create(path:)
+      Dir.mkdir(File.expand_path(path))
+    rescue Errno::EEXIST
+      # Do nothing
+    end
+
+    def exist(path:)
+      Dir.exist? File.expand_path(path)
+    end
+
+    def delete(path:)
+      Dir.delete(File.expand_path(path))
+    end
+
     def permit(command, path:, **)
       @entitlement.paths.permitted? path
     end

data/lib/terminalwire/client.rb

@@ -23,6 +23,7 @@ module Terminalwire
           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:)
         end
       end
 
@@ -53,14 +54,14 @@ module Terminalwire
     def self.tcp(...)
       socket = TCPSocket.new(...)
       transport = Terminalwire::Transport::Socket.new(socket)
-      adapter = Terminalwire::Adapter.new(transport)
+      adapter = Terminalwire::Adapter::Socket.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)
+      adapter = Terminalwire::Adapter::Socket.new(transport)
       Terminalwire::Client::Handler.new(adapter)
     end
 
@@ -84,7 +85,7 @@ module Terminalwire
 
         Async::WebSocket::Client.connect(endpoint) do |adapter|
           transport = Terminalwire::Transport::WebSocket.new(adapter)
-          adapter = Terminalwire::Adapter.new(transport)
+          adapter = Terminalwire::Adapter::Socket.new(transport)
           entitlement ||= Entitlement.from_url(url)
           Terminalwire::Client::Handler.new(adapter, arguments:, entitlement:).connect
         end

data/lib/terminalwire/server/context.rb

@@ -0,0 +1,42 @@
+require "fileutils"
+
+module Terminalwire::Server
+  class Context
+    extend Forwardable
+
+    attr_reader :stdout, :stdin, :stderr, :browser, :file, :directory, :storage_path
+
+    def_delegators :@stdout, :puts, :print
+    def_delegators :@stdin, :gets, :getpass
+
+    def initialize(adapter:, entitlement:)
+      @adapter = adapter
+
+      @entitlement = entitlement
+      @storage_path = Pathname.new(entitlement.fetch(:storage_path))
+
+      @stdout = Resource::STDOUT.new("stdout", @adapter)
+      @stdin = Resource::STDIN.new("stdin", @adapter)
+      @stderr = Resource::STDERR.new("stderr", @adapter)
+      @browser = Resource::Browser.new("browser", @adapter)
+      @file = Resource::File.new("file", @adapter)
+      @directory = Resource::Directory.new("directory", @adapter)
+
+      if block_given?
+        begin
+          yield self
+        ensure
+          exit
+        end
+      end
+    end
+
+    def exit(status = 0)
+      @adapter.write(event: "exit", status: status)
+    end
+
+    def close
+      @adapter.close
+    end
+  end
+end

data/lib/terminalwire/server/resource.rb

@@ -0,0 +1,100 @@
+module Terminalwire::Server
+  module Resource
+    class Base < Terminalwire::Resource::Base
+      private
+
+      def command(command, **parameters)
+        @adapter.write(
+          event: "resource",
+          name: @name,
+          action: "command",
+          command: command,
+          parameters: parameters
+        )
+        @adapter.recv&.fetch(:response)
+      end
+    end
+
+    class STDOUT < Base
+      def puts(data)
+        command("print_line", data: data)
+      end
+
+      def print(data)
+        command("print", data: data)
+      end
+
+      def flush
+        # Do nothing
+      end
+    end
+
+    class STDERR < STDOUT
+    end
+
+    class STDIN < Base
+      def getpass
+        command("read_password")
+      end
+
+      def gets
+        command("read_line")
+      end
+    end
+
+    class File < Base
+      def read(path)
+        command("read", path: path.to_s)
+      end
+
+      def write(path, content)
+        command("write", path: path.to_s, content:)
+      end
+
+      def append(path, content)
+        command("append", path: path.to_s, content:)
+      end
+
+      def delete(path)
+        command("delete", path: path.to_s)
+      end
+      alias :rm :delete
+
+      def exist?(path)
+        command("exist", path: path.to_s)
+      end
+
+      def change_mode(path, mode)
+        command("change_mode", path: path.to_s, mode:)
+      end
+      alias :chmod :change_mode
+    end
+
+    class Directory < Base
+      def list(path)
+        command("list", path: path.to_s)
+      end
+      alias :ls :list
+
+      def create(path)
+        command("create", path: path.to_s)
+      end
+      alias :mkdir :create
+
+      def exist?(path)
+        command("exist", path: path.to_s)
+      end
+
+      def delete(path)
+        command("delete", path: path.to_s)
+      end
+      alias :rm :delete
+    end
+
+    class Browser < Base
+      def launch(url)
+        command("launch", url: url)
+      end
+    end
+  end
+end

data/lib/terminalwire/server.rb

@@ -2,121 +2,6 @@ require "thor"
 
 module Terminalwire
   module Server
-    module Resource
-      class Base < Terminalwire::Resource::Base
-        private
-
-        def command(command, **parameters)
-          @adapter.write(
-            event: "resource",
-            name: @name,
-            action: "command",
-            command: command,
-            parameters: parameters
-          )
-          @adapter.recv&.fetch(:response)
-        end
-      end
-
-      class STDOUT < Base
-        def puts(data)
-          command("print_line", data: data)
-        end
-
-        def print(data)
-          command("print", data: data)
-        end
-
-        def flush
-          # Do nothing
-        end
-      end
-
-      class STDERR < STDOUT
-      end
-
-      class STDIN < Base
-        def getpass
-          command("read_password")
-        end
-
-        def gets
-          command("read_line")
-        end
-      end
-
-      class File < Base
-        def read(path)
-          command("read", path: path.to_s)
-        end
-
-        def write(path, content)
-          command("write", path: path.to_s, content:)
-        end
-
-        def append(path, content)
-          command("append", path: path.to_s, content:)
-        end
-
-        def mkdir(path)
-          command("mkdir", path: path.to_s)
-        end
-
-        def delete(path)
-          command("delete", path: path.to_s)
-        end
-
-        def exist?(path)
-          command("exist", path: path.to_s)
-        end
-      end
-
-      class Browser < Base
-        def launch(url)
-          command("launch", url: url)
-        end
-      end
-    end
-
-    class Context
-      extend Forwardable
-
-      attr_reader :stdout, :stdin, :stderr, :browser, :file, :storage_path
-
-      def_delegators :@stdout, :puts, :print
-      def_delegators :@stdin, :gets, :getpass
-
-      def initialize(adapter:, entitlement:)
-        @adapter = adapter
-
-        # TODO: Encapsulate entitlement in a class instead of a hash.
-        @entitlement = entitlement
-        @storage_path = Pathname.new(entitlement.fetch(:storage_path))
-
-        @stdout = Server::Resource::STDOUT.new("stdout", @adapter)
-        @stdin = Server::Resource::STDIN.new("stdin", @adapter)
-        @stderr = Server::Resource::STDERR.new("stderr", @adapter)
-        @browser = Server::Resource::Browser.new("browser", @adapter)
-        @file = Server::Resource::File.new("file", @adapter)
-
-        if block_given?
-          begin
-            yield self
-          ensure
-            exit
-          end
-        end
-      end
-
-      def exit(status = 0)
-        @adapter.write(event: "exit", status: status)
-      end
-
-      def close
-        @adapter.close
-      end
-    end
-
     class MyCLI < ::Thor
       include Terminalwire::Thor
 
@@ -161,7 +46,7 @@ module Terminalwire
 
       def call(env)
         Async::WebSocket::Adapters::Rack.open(env, protocols: ['ws']) do |connection|
-          run(Adapter.new(Terminalwire::Transport::WebSocket.new(connection)))
+          run(Adapter::Socket.new(Terminalwire::Transport::WebSocket.new(connection)))
         end or [200, { "Content-Type" => "text/plain" }, ["Connect via WebSockets"]]
       end
 

data/lib/terminalwire/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Terminalwire
-  VERSION = "0.1.7"
+  VERSION = "0.1.8"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: terminalwire
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.8
 platform: ruby
 authors:
 - Brad Gessler
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-20 00:00:00.000000000 Z
+date: 2024-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async-websocket
@@ -167,6 +167,8 @@ files:
 - lib/terminalwire/logging.rb
 - lib/terminalwire/rails.rb
 - lib/terminalwire/server.rb
+- lib/terminalwire/server/context.rb
+- lib/terminalwire/server/resource.rb
 - lib/terminalwire/thor.rb
 - lib/terminalwire/transport.rb
 - lib/terminalwire/version.rb