terminalwire 0.3.5.alpha2 → 2.0.0

data/lib/terminalwire/v2/rails.rb

@@ -0,0 +1,335 @@
+# frozen_string_literal: true
+
+require "forwardable"
+require "pathname"
+require "json"
+require "jwt" # legacy (signed-only) session read + migration
+require "active_support/key_generator"
+require "active_support/message_encryptor"
+require "active_support/core_ext/time" # Time#advance, used by expires_in:
+
+require "terminalwire/v2"                  # full v2 server (runtime, handler, …)
+require "terminalwire/v2/server/rack"      # the v2 Rack endpoint
+require "terminalwire/v2/server/dual_thor" # one Thor CLI, both protocols
+
+# Rails `session` parity (v1 -> v2 with NO Thor app changes). v1's Rails shell
+# (Terminalwire::Rails::Thor::Shell) exposes a JWT-backed `session`; the plain v2
+# shell doesn't — so unchanged v1 Thor code that touches `session` (current_user,
+# whoami, login) raised NoMethodError over v2. Reopen the v2 shell to provide the
+# SAME session, backed by the protocol-agnostic context (file/directory/storage_path,
+# which v2 implements identically). PUBLIC, not protected: Ruby 4's Forwardable —
+# used by the v1 `def_delegators :shell, :session` — refuses to forward to a
+# non-public method (the "forwarding to private method" warning is now a hard error).
+# Backed by the v2-native Terminalwire::V2::Rails::Session (below) — no v1 gem needed.
+Terminalwire::V2::Server::Thor::Shell.class_eval do
+  def session
+    @session ||= Terminalwire::V2::Rails::Session.new(context: context)
+  end
+end
+
+# Delegate `session` from the CLI instance to its shell — matching v1's
+# `def_delegators :shell, :session` — so unchanged Thor code that calls `session`
+# (current_user, login, whoami) works over v2 without app changes.
+Terminalwire::V2::Server::Thor::Helpers.module_eval do
+  def session = shell.session
+end
+
+module Terminalwire
+  module V2
+    # Drop-in Rails integration for serving a Terminalwire CLI over BOTH the v1
+    # and v2 wire on a SINGLE endpoint during the transition. The whole wiring is
+    # one line in config/routes.rb:
+    #
+    #   require "terminalwire/v2/rails"
+    #   match "/terminal", to: Terminalwire::V2::Rails.dual_terminal(MainTerminal),
+    #                      via: [:get, :connect]
+    #
+    # A v2 client advertises the `terminalwire.v2` WebSocket subprotocol on the
+    # upgrade; the dispatcher detects that (before the socket is accepted) and routes
+    # to the v2 server, otherwise to the unchanged v1 handler. Same URL for both —
+    # the exec launcher's `url:` never changes. `dualize` extends the Thor tree so
+    # it's the SAME CLI answering on either wire, not a v2 fork.
+    #
+    # For a v2-only app (no v1 sub-gems), skip this and just
+    # `mount Terminalwire::V2::Server::Rack.new(cli)` directly.
+    module Rails
+      SUBPROTOCOL = "terminalwire.v2"
+
+      # A session stored on the CLIENT — the v2-native version of v1's
+      # Terminalwire::Rails::Session, so a v2-only app needs no v1 gem. It reads/writes
+      # via the context (file/directory/storage_path, which v2 implements identically
+      # to v1).
+      #
+      # The payload is ENCRYPTED and signed (ActiveSupport::MessageEncryptor,
+      # AES-256-GCM — the same primitive behind Rails' encrypted cookies), so the
+      # contents are confidential on the client machine, not just tamper-proof. The
+      # key is derived from the app's secret_key_base with a Terminalwire-specific
+      # salt, so it is never the raw secret and never shared with any other
+      # verifier/encryptor in the app. Sessions expire (default 30 days, clock reset
+      # on every write); an expired session reads as empty.
+      #
+      # Earlier releases stored the session as an HS256 JWT — signed but NOT
+      # encrypted, despite docs saying otherwise. Those legacy sessions are read one
+      # last time and immediately rewritten encrypted, so upgrading logs nobody out.
+      #
+      # Resilient by design: a missing, empty, tampered, expired, or wrong-key session
+      # reads as EMPTY, so the user simply logs in again — upgrading (or rotating the
+      # secret) never crashes a command, it just signs them out.
+      class Session
+        # Kept from the JWT era so upgraded clients keep using the same file.
+        FILENAME = "session.jwt"
+        EMPTY_SESSION = {}.freeze
+        # Key-derivation salt — Terminalwire-specific so the derived key can't
+        # collide with any key the app derives from secret_key_base elsewhere.
+        KEY_SALT = "terminalwire session"
+        # AEAD cipher: encrypts AND authenticates in one primitive (the same one
+        # behind Rails' encrypted cookies). Pinned explicitly, not left to the app's
+        # ActiveSupport default (which is aes-256-cbc unless configured otherwise).
+        CIPHER = "aes-256-gcm"
+        DEFAULT_EXPIRES_IN = 60 * 60 * 24 * 30 # 30 days, refreshed on every write
+
+        extend Forwardable
+        def_delegators :read, :dig, :fetch, :[]
+
+        def initialize(context:, path: nil, secret_key: self.class.secret_key, expires_in: DEFAULT_EXPIRES_IN)
+          @context = context
+          @path = Pathname.new(path || context.storage_path)
+          @config_file_path = @path.join(FILENAME)
+          @secret_key = secret_key
+          @expires_in = expires_in
+          ensure_file
+        end
+
+        # The session payload, or EMPTY_SESSION when there isn't a valid one (missing,
+        # empty, tampered, expired, wrong key, unreadable). To the user these all mean
+        # the same thing — log in again — so none of them raise.
+        def read
+          token = @context.file.read(@config_file_path)
+          return EMPTY_SESSION if token.nil? || token.to_s.empty?
+
+          encryptor.decrypt_and_verify(token) || EMPTY_SESSION
+        rescue ActiveSupport::MessageEncryptor::InvalidMessage
+          read_and_migrate_legacy(token)
+        rescue StandardError
+          EMPTY_SESSION
+        end
+
+        def reset
+          @context.file.delete(@config_file_path)
+        rescue StandardError
+          nil
+        end
+
+        def edit
+          config = read.dup
+          yield config
+          write(config)
+        end
+
+        def []=(key, value)
+          edit { |config| config[key] = value }
+        end
+
+        def write(config)
+          token = encryptor.encrypt_and_sign(config, expires_in: @expires_in)
+          @context.file.write(@config_file_path, token)
+        end
+
+        def self.secret_key
+          ::Rails.application.secret_key_base
+        end
+
+        private
+
+        def encryptor
+          @encryptor ||= ActiveSupport::MessageEncryptor.new(derived_key, cipher: CIPHER, serializer: JSON)
+        end
+
+        # Explicit digest so the key doesn't shift with the app's
+        # ActiveSupport::KeyGenerator.hash_digest_class config (which would silently
+        # invalidate every session).
+        def derived_key
+          ActiveSupport::KeyGenerator
+            .new(@secret_key, iterations: 1000, hash_digest_class: OpenSSL::Digest::SHA256)
+            .generate_key(KEY_SALT, ActiveSupport::MessageEncryptor.key_len(CIPHER))
+        end
+
+        # Sessions written by earlier releases are HS256 JWTs: signed, NOT encrypted.
+        # Verify one last time and immediately rewrite encrypted, so upgrading never
+        # logs anyone out. Anything unreadable is just an empty session.
+        def read_and_migrate_legacy(token)
+          payload = JWT.decode(token, @secret_key, true, algorithm: "HS256").first
+          return EMPTY_SESSION unless payload
+
+          write(payload)
+          payload
+        rescue StandardError
+          EMPTY_SESSION
+        end
+
+        # Best-effort: seed an empty session file if absent. A failure here is not
+        # fatal — read/write degrade gracefully on their own.
+        def ensure_file
+          return true if file_exist?
+
+          @context.directory.create(@path)
+          write(EMPTY_SESSION)
+        rescue StandardError
+          nil
+        end
+
+        def file_exist?
+          @context.file.exist?(@config_file_path)
+        rescue StandardError
+          false
+        end
+      end
+
+      # Drop-in Rails terminal mixin — the v2 equivalent of v1's `Terminalwire::Thor`.
+      # `include Terminalwire::V2::Rails::Thor` in your Thor CLI and it:
+      #   * streams I/O over the v2 wire (Terminalwire::V2::Server::Thor),
+      #   * exposes the client `session` (the shell delegator), and
+      #   * mixes in Rails route URL helpers (root_url, *_url, *_path) so commands like
+      #     login/browser-open can build links. The per-connection host is set by the
+      #     handler, so the *_url helpers resolve to the host the client connected on.
+      # The url_helpers go in `no_commands` so Thor doesn't register them as commands.
+      module Thor
+        def self.included(base)
+          base.include Terminalwire::V2::Server::Thor
+          base.class_eval do
+            no_commands do
+              include ::Rails.application.routes.url_helpers
+            end
+          end
+        end
+      end
+
+      # Returns a Rack endpoint that serves `cli` over both protocols. Pass `v1:`/`v2:`
+      # to override the handlers (tests, custom adapters); by default it builds the
+      # stock v1 `Terminalwire::Rails::Thor` and v2 `Terminalwire::V2::Server::Rack`.
+      def self.dual_terminal(cli, v1: nil, v2: nil)
+        Terminalwire::V2::Server.dualize(cli)
+        Dispatcher.new(
+          v1: v1 || default_v1(cli),
+          v2: v2 || Terminalwire::V2::Server::Rack.new(cli, verbose: verbose?, report: report)
+        )
+      end
+
+      # The v2-DEFAULT endpoint: serve `cli` over v2, with no v1. Mount it the same way
+      # as dual_terminal:
+      #
+      #   match "/terminal", to: Terminalwire::V2::Rails.terminal(MainTerminal),
+      #                      via: [:get, :connect]
+      #
+      # It returns a version endpoint (not the bare Rack): a connection advertising the
+      # `terminalwire.v2` subprotocol — and any connection that doesn't ask for another
+      # version — is served by the v2 server. The endpoint is the forward-compatible
+      # seam: a future v3 registers another handler here without changing the app's
+      # route. (A bare Rack handed to `match to:` drops streaming output in production;
+      # the endpoint, like dual_terminal's, is what Rails routing needs.)
+      def self.terminal(cli, verbose: nil, report: nil)
+        Terminalwire::V2::Server.terminalize(cli)
+        v2 = Terminalwire::V2::Server::Rack.new(
+          cli,
+          verbose: verbose.nil? ? verbose?() : verbose,
+          report: report || self.report
+        )
+        VersionEndpoint.new(default: v2, by_subprotocol: { SUBPROTOCOL => v2 })
+      end
+
+      # In dev/test, show the full backtrace to the client (consider_all_requests_local,
+      # like v1). In production the client sees the generic message — but the real
+      # exception is still LOGGED + reported (below), never silently swallowed.
+      def self.verbose?
+        ::Rails.application.config.consider_all_requests_local
+      rescue StandardError
+        false
+      end
+
+      # Log + report unexpected command errors to Rails (mirrors the v1 handler).
+      # Without this the v2 Handler drops the exception on the floor behind the
+      # generic message, which is exactly what made the missing-host bug hard to find.
+      def self.report
+        lambda do |error|
+          ::Rails.error.report(error, handled: true) if ::Rails.respond_to?(:error)
+          ::Rails.logger&.error("terminalwire: #{error.class}: #{error.message}\n#{Array(error.backtrace).join("\n")}")
+        end
+      end
+
+      # Lazily resolve the v1 handler so this gem doesn't hard-depend on the v1
+      # `terminalwire-rails` gem at load time. Apps doing the transition have it;
+      # if not, fail with a clear message instead of a NameError.
+      def self.default_v1(cli)
+        unless defined?(Terminalwire::Rails::Thor)
+          raise "terminalwire/v2/rails: the v1 handler (Terminalwire::Rails::Thor) " \
+                "isn't loaded. Add the v1 `terminalwire-rails` gem, or pass v2:-only " \
+                "and mount Terminalwire::V2::Server::Rack directly for a v2-only app."
+        end
+        Terminalwire::Rails::Thor.new(cli)
+      end
+
+      # Routes a WebSocket upgrade to the v1 or v2 handler by inspecting the
+      # advertised subprotocol on the Rack env — no socket is accepted until the
+      # branch is chosen, so a connection only ever reaches one handler.
+      class Dispatcher
+        def initialize(v1:, v2:)
+          @v1 = v1
+          @v2 = v2
+        end
+
+        def call(env)
+          protos = env["HTTP_SEC_WEBSOCKET_PROTOCOL"].to_s.split(/,\s*/)
+          (protos.include?(SUBPROTOCOL) ? @v2 : @v1).call(env)
+        end
+      end
+
+      # Routes a WebSocket upgrade to a handler by the version subprotocol it advertises,
+      # falling back to `default` (v2) when none matches — the forward-compatible seam for
+      # registering future protocol versions. Same Rack-endpoint shape as Dispatcher, so
+      # Rails `match to:` hands the connection off correctly in production.
+      class VersionEndpoint
+        def initialize(default:, by_subprotocol: {})
+          @default = default
+          @by_subprotocol = by_subprotocol
+        end
+
+        def call(env)
+          protos = env["HTTP_SEC_WEBSOCKET_PROTOCOL"].to_s.split(/,\s*/)
+          handler = protos.lazy.filter_map { |proto| @by_subprotocol[proto] }.first || @default
+          handler.call(env)
+        end
+      end
+    end
+  end
+end
+
+# --- Drop-in v1 API -----------------------------------------------------------
+# A 1.x/0.x app upgrades to v2 by bumping the gem version and redeploying — nothing
+# else. Its unchanged `include Terminalwire::Thor` and
+# `match "/terminal", to: Terminalwire::Rails::Thor.new(MainTerminal)` keep working,
+# now serving v2, because these names resolve to the v2 implementations.
+#
+# Guarded with `defined?` so a transitional app that still loads the v1 gems keeps
+# v1's classes (and drives both wires with `dual_terminal` explicitly); only a
+# v2-only app (no v1 gems) picks up these.
+module Terminalwire
+  # `include Terminalwire::Thor` -> the v2 Rails terminal mixin.
+  Thor = V2::Rails::Thor unless defined?(Terminalwire::Thor)
+
+  module Rails
+    # `Terminalwire::Rails::Thor.new(cli)` -> a Rack endpoint serving `cli` over v2,
+    # mounted exactly like the v1 handler was.
+    unless defined?(Terminalwire::Rails::Thor)
+      class Thor
+        def initialize(cli)
+          @app = Terminalwire::V2::Rails.terminal(cli)
+        end
+
+        def call(env) = @app.call(env)
+      end
+    end
+
+    # `Terminalwire::Rails::Session` -> the v2-native client session.
+    Session = V2::Rails::Session unless defined?(Terminalwire::Rails::Session)
+  end
+end

data/lib/terminalwire/v2/server/connection.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module Terminalwire::V2
+  module Server
+    # The server-role protocol state machine. Sans-IO: the application feeds it
+    # incoming frames via #receive (getting back directives) and asks it to build
+    # outgoing frames via the helper methods. No sockets, threads, or clock.
+    #
+    # A "directive" returned from #receive is one of:
+    #   [:send, frame_hash]              — write this frame to the transport
+    #   [:event, name_symbol, payload]   — a domain event for the application
+    class Connection
+      attr_reader :state, :protocol, :capabilities
+
+      def initialize(server_min: Protocol::MIN_VERSION,
+                     server_max: Protocol::MAX_VERSION,
+                     server_capabilities: Protocol::CAPABILITIES,
+                     mux: Mux.new)
+        @server_min = server_min
+        @server_max = server_max
+        @server_capabilities = server_capabilities
+        @mux = mux
+        @state = :awaiting_hello
+        @protocol = nil
+        @capabilities = []
+      end
+
+      def ready?
+        @state == :ready
+      end
+
+      # Feed one incoming frame. Returns an Array of directives (see class docs).
+      def receive(frame)
+        case @state
+        when :awaiting_hello then on_hello(frame)
+        when :ready          then on_ready(frame)
+        else
+          raise ProtocolError, "received #{frame["t"].inspect} while #{@state}"
+        end
+      end
+
+      # --- application-driven outgoing helpers ---------------------------------
+
+      # Open a stream (:stdout/:stderr output, or a stdin-raw input stream with a
+      # line-discipline mode). Returns [sid, frame].
+      def open_stream(stream, mode: nil)
+        require_ready!
+        sid = @mux.allocate
+        [sid, Frames.open(sid: sid, stream: stream.to_s, mode: mode)]
+      end
+
+      # Build a data frame for an open output stream.
+      def write(sid, bytes)
+        require_ready!
+        Frames.data(sid: sid, bytes: bytes)
+      end
+
+      def close_stream(sid)
+        require_ready!
+        Frames.close(sid: sid)
+      end
+
+      # Issue a resource request. Returns [sid, frame]; the response will arrive
+      # later via #receive as [:event, :response, ...].
+      def call(resource, method, params = {})
+        require_ready!
+        sid = @mux.allocate
+        @mux.register(sid, { resource: resource, method: method })
+        [sid, Frames.request(sid: sid, resource: resource.to_s, method: method.to_s, params: params)]
+      end
+
+      def exit(status = 0)
+        @state = :closed
+        Frames.exit(status: status)
+      end
+
+      private
+
+      def on_hello(frame)
+        unless frame["t"] == Protocol::Type::HELLO
+          raise ProtocolError, "expected hello, got #{frame["t"].inspect}"
+        end
+
+        protocol = frame["protocol"]
+        capabilities = frame["capabilities"]
+        # Validate hello-specific fields up front so a malformed hello is a clean
+        # ProtocolError rather than a NoMethodError deep in the negotiator.
+        raise ProtocolError, "hello protocol must be an integer" unless protocol.is_a?(Integer)
+        raise ProtocolError, "hello capabilities must be an array" unless capabilities.is_a?(Array)
+
+        result = Negotiator.negotiate(
+          client_protocol: protocol,
+          client_capabilities: capabilities,
+          server_min: @server_min,
+          server_max: @server_max,
+          server_capabilities: @server_capabilities
+        )
+
+        if result[:decision] == "welcome"
+          @state = :ready
+          @protocol = result[:protocol]
+          @capabilities = result[:capabilities]
+          [
+            [:send, Frames.welcome(protocol: @protocol, capabilities: @capabilities)],
+            [:event, :ready, { protocol: @protocol, capabilities: @capabilities,
+                               program: frame["program"], entitlement: frame["entitlement"],
+                               terminal: frame["terminal"], flow: frame["flow"] }]
+          ]
+        else
+          @state = :closed
+          message = "client speaks #{frame["protocol"]}; " \
+                    "server supports #{@server_min}..#{@server_max}"
+          [
+            [:send, Frames.incompatible(supported: result[:supported], message: message)],
+            [:event, :incompatible, { supported: result[:supported] }]
+          ]
+        end
+      end
+
+      # Single uniform dispatch over the inbound frame type (mirrors the Go
+      # client's Process switch). Every client->server-while-ready frame is one
+      # case here; an unrecognized type is a protocol violation.
+      def on_ready(frame)
+        case frame["t"]
+        when Protocol::Type::SIGNAL      then on_signal(frame)
+        when Protocol::Type::WINDOW_ADJUST
+          sid = frame["sid"]
+          bytes = frame["bytes"]
+          # Ignore a malformed grant rather than letting it through: a negative
+          # `bytes` would drive the window negative and permanently stall the
+          # stream, and a non-integer would crash the pump thread (TypeError).
+          if sid.is_a?(Integer) && bytes.is_a?(Integer) && bytes >= 0
+            [[:event, :window_adjust, { sid: sid, bytes: bytes }]]
+          else
+            []
+          end
+        when Protocol::Type::DATA        then on_input(frame)
+        when Protocol::Type::RESPONSE    then on_response(frame)
+        else
+          raise ProtocolError, "unexpected #{frame["t"].inspect} while ready"
+        end
+      end
+
+      # Unsolicited terminal signals (resize/interrupt). Unknown names are ignored
+      # for forward compatibility — a newer client can send signals we don't know.
+      def on_signal(frame)
+        case frame["name"]
+        when Protocol::Signal::RESIZE
+          [[:event, :resize, { cols: frame["cols"], rows: frame["rows"] }]]
+        when Protocol::Signal::INTERRUPT
+          [[:event, :interrupt, {}]]
+        else
+          []
+        end
+      end
+
+      # Client -> server data: keystrokes on a raw input stream the server opened.
+      def on_input(frame)
+        [[:event, :input, { sid: frame["sid"], bytes: frame["bytes"] }]]
+      end
+
+      def on_response(frame)
+        # A response for an unknown/already-resolved stream (duplicate, late, or
+        # hostile) is ignored rather than crashing the session.
+        return [] unless @mux.pending?(frame["sid"])
+
+        context = @mux.resolve(frame["sid"])
+        [[:event, :response, {
+          sid: frame["sid"], ok: frame["ok"], value: frame["value"],
+          error: frame["error"], context: context
+        }]]
+      end
+
+      def require_ready!
+        raise ProtocolError, "connection not ready (state: #{@state})" unless ready?
+      end
+    end
+  end
+end