pinesandbox 0.0.1 → 0.3.18

data/lib/pinesandbox/computer_binding.rb

@@ -0,0 +1,47 @@
+require "json"
+
+module PineSandbox
+  class Computer
+    # A saved connection to one runtime. Store with Credentials in encrypted
+    # application storage. Importing it neither contacts nor replaces the runtime.
+    class Binding < Struct.new(:computer_id, :runtime_id, :computer_token,
+                               :binding_revision, keyword_init: true)
+      SCHEMA = 1
+
+      def self.from_json(json)
+        data = JSON.parse(json)
+        unless data.is_a?(Hash) && data["schema"].is_a?(Integer) && data["schema"] == SCHEMA
+          raise ArgumentError, "unsupported Computer binding schema"
+        end
+        new(computer_id: data["computer_id"], runtime_id: data["runtime_id"],
+            computer_token: data["computer_token"], binding_revision: data["binding_revision"]).validate!
+      rescue JSON::ParserError
+        raise ArgumentError, "Computer binding must be valid JSON"
+      end
+
+      def validate!
+        unless computer_id.is_a?(String) && computer_id.match?(Computer::UUID_V7)
+          raise ArgumentError, "binding computer_id must be a lowercase UUIDv7"
+        end
+        unless runtime_id.is_a?(String) && runtime_id.length <= 63 && runtime_id.match?(Zone::RUNTIME_ID_RE)
+          raise ArgumentError, "binding runtime_id must be a runtime identifier"
+        end
+        unless computer_token.is_a?(String) && computer_token.match?(/\Act_[!-~]+\z/)
+          raise ArgumentError, "binding computer_token must be a Computer token"
+        end
+        unless binding_revision.is_a?(Integer) && binding_revision.between?(0, (2**63) - 1)
+          raise ArgumentError, "binding revision must be a non-negative integer"
+        end
+        self
+      end
+
+      def to_json(*args)
+        validate!
+        { schema: SCHEMA, computer_id:, runtime_id:, computer_token:, binding_revision: }.to_json(*args)
+      end
+
+      def inspect = "#<PineSandbox::Computer::Binding computer_id=#{computer_id} runtime_id=#{runtime_id} token=[redacted]>"
+      alias_method :to_s, :inspect
+    end
+  end
+end

data/lib/pinesandbox/computer_credentials.rb

@@ -0,0 +1,175 @@
+require "base64"
+require "json"
+
+module PineSandbox
+  class Computer
+    # Caller-owned secrets for starting a Computer. JSON contains secret bytes
+    # encoded as Base64; store it in your application's encrypted storage.
+    # Keep Struct readers, writers and raw to_h values; the member set expands.
+    class Credentials < Struct.new(:id, :key, :capture_keypair, :prior_capture_keypairs,
+                                   :prior_keys, :ephemeral, keyword_init: true)
+      SCHEMA = 1
+
+      def self.from_json(json)
+        from_serialized_hash(JSON.parse(json))
+      rescue JSON::ParserError
+        raise ArgumentError, "credentials must be valid JSON"
+      end
+
+      def self.from_serialized_hash(hash)
+        raise ArgumentError, "computer credentials must be a Hash" unless hash.is_a?(Hash)
+
+        data = hash.transform_keys(&:to_s)
+        # Released Go credentials used encoding/json's exported field names.
+        # Accept those saved records, but always write the shared schema.
+        if !data.key?("schema") && data.key?("ID")
+          pair = data["CaptureKeypair"]
+          raise ArgumentError, "capture keypair must be an object" unless pair.is_a?(Hash)
+          data = {"schema" => SCHEMA, "id" => data["ID"], "key" => data["Key"],
+                  "capture_keypair" => {"generation" => pair["Generation"], "pk" => pair["PK"], "sk" => pair["SK"]}}
+        end
+        schema = data["schema"]
+        unless schema.is_a?(Integer) && schema == SCHEMA
+          raise ArgumentError, "unsupported computer credentials schema (expected #{SCHEMA})"
+        end
+
+        prior_capture_keypairs = data.fetch("prior_capture_keypairs", [])
+        unless prior_capture_keypairs.is_a?(Array)
+          raise ArgumentError, "prior_capture_keypairs must be an Array"
+        end
+
+        new(
+          id: fetch_string(data, "id"),
+          key: decode(fetch_string(data, "key"), "key"),
+          ephemeral: data.fetch("ephemeral", false),
+          capture_keypair: data["capture_keypair"] && keypair_from_h(data["capture_keypair"]),
+          prior_capture_keypairs: prior_capture_keypairs.map { |entry| keypair_from_h(entry) },
+          prior_keys: prior_keys_from(data.fetch("prior_keys", []))
+        ).validate!
+      end
+
+      def self.prior_keys_from(entries)
+        raise ArgumentError, "prior_keys must be an Array" unless entries.is_a?(Array)
+
+        pairs = entries.map do |entry|
+          raise ArgumentError, "prior_keys entries must be Hashes" unless entry.is_a?(Hash)
+
+          entry = entry.transform_keys(&:to_s)
+          [ entry.fetch("version") { raise ArgumentError, "prior key is missing version" },
+            decode(fetch_string(entry, "key"), "prior key") ]
+        end
+        raise ArgumentError, "prior_keys versions must be distinct" if pairs.map(&:first).uniq.length != pairs.length
+
+        pairs.to_h
+      end
+      private_class_method :prior_keys_from
+
+      def initialize(id: nil, key: nil, ephemeral: false, capture_keypair: nil,
+                     prior_capture_keypairs: [], prior_keys: {})
+        super(id: id&.dup, key: key&.dup, capture_keypair: capture_keypair,
+              prior_capture_keypairs: prior_capture_keypairs, prior_keys: prior_keys,
+              ephemeral: ephemeral)
+      end
+
+      def validate!
+        raise ArgumentError, "id must be a lowercase UUIDv7" unless id.is_a?(String) && id.match?(Computer::UUID_V7)
+        raise ArgumentError, "key must be 32 raw bytes" unless key.is_a?(String) && key.bytesize == 32
+        raise ArgumentError, "ephemeral must be true or false" unless [ true, false ].include?(ephemeral)
+        unless capture_keypair.nil? || capture_keypair.is_a?(CaptureKeypair)
+          raise ArgumentError, "capture_keypair must be a PineSandbox::CaptureKeypair"
+        end
+        if !ephemeral && capture_keypair.nil?
+          raise ArgumentError, "persistent Computer credentials require capture_keypair"
+        end
+        unless prior_capture_keypairs.is_a?(Array) && prior_capture_keypairs.all? { |keypair| keypair.is_a?(CaptureKeypair) }
+          raise ArgumentError, "prior_capture_keypairs must contain only PineSandbox::CaptureKeypair values"
+        end
+        prior_generations = prior_capture_keypairs.map(&:generation)
+        if prior_generations.any? && capture_keypair.nil?
+          raise ArgumentError, "prior_capture_keypairs require capture_keypair"
+        end
+        if prior_generations.uniq.length != prior_generations.length ||
+           prior_generations.any? { |generation| generation >= capture_keypair.generation }
+          raise ArgumentError, "prior capture keypair generations must be distinct and below the current generation"
+        end
+        unless prior_keys.is_a?(Hash) && prior_keys.all? { |version, bytes| version.is_a?(Integer) && bytes.is_a?(String) && bytes.bytesize == 32 }
+          raise ArgumentError, "prior_keys must map Integer versions to 32 raw bytes"
+        end
+        if prior_keys.key?(Computer::CURRENT_KEY_VERSION)
+          raise ArgumentError, "prior_keys must not include the current key version #{Computer::CURRENT_KEY_VERSION}"
+        end
+
+        self
+      end
+
+      def ephemeral?
+        ephemeral
+      end
+
+      # JSON contains secrets; ordinary Struct#to_h retains raw Ruby values.
+      def serialized_hash
+        validate!
+        {
+          "schema" => SCHEMA,
+          "id" => id.dup,
+          "key" => Base64.strict_encode64(key),
+          "ephemeral" => ephemeral?,
+          "capture_keypair" => capture_keypair && self.class.keypair_to_h(capture_keypair),
+          "prior_capture_keypairs" => prior_capture_keypairs.sort_by(&:generation).map { |keypair| self.class.keypair_to_h(keypair) },
+          "prior_keys" => prior_keys.sort.map { |version, bytes| { "version" => version, "key" => Base64.strict_encode64(bytes) } }
+        }
+      end
+
+      def to_json(*args)
+        serialized_hash.to_json(*args)
+      end
+
+      def inspect
+        "#<PineSandbox::Computer::Credentials id=#{id.inspect} " \
+          "ephemeral=#{ephemeral?} key=[redacted] capture_keypair=[redacted]>"
+      end
+      alias_method :to_s, :inspect
+
+      private :serialized_hash
+      private_class_method :from_serialized_hash
+
+      class << self
+        def keypair_to_h(keypair)
+          {
+            "generation" => keypair.generation,
+            "pk" => Base64.strict_encode64(keypair.pk),
+            "sk" => Base64.strict_encode64(keypair.sk)
+          }
+        end
+
+        private
+
+        def keypair_from_h(entry)
+          raise ArgumentError, "capture keypair entries must be Hashes" unless entry.is_a?(Hash)
+
+          entry = entry.transform_keys(&:to_s)
+          CaptureKeypair.new(
+            generation: entry.fetch("generation") { raise ArgumentError, "capture keypair is missing generation" },
+            pk: decode(fetch_string(entry, "pk"), "capture keypair pk"),
+            sk: decode(fetch_string(entry, "sk"), "capture keypair sk")
+          )
+        end
+
+        def fetch_string(data, name)
+          value = data[name]
+          raise ArgumentError, "computer credentials field #{name} must be a String" unless value.is_a?(String)
+
+          value
+        end
+
+        def decode(value, label)
+          decoded = Base64.strict_decode64(value)
+          raise ArgumentError unless Base64.strict_encode64(decoded) == value
+          decoded
+        rescue ArgumentError
+          raise ArgumentError, "computer credentials field #{label} is not strict Base64"
+        end
+      end
+    end
+  end
+end

data/lib/pinesandbox/connection.rb

@@ -0,0 +1,26 @@
+require_relative "zone"
+require_relative "clock"
+
+module PineSandbox
+  # Internal value object bundling everything Computer#attach needs against the
+  # Computer gateway: the `attach_provider` (mints per-attach {bind_token,
+  # broker_grant} — the pk_-backed portal source or an in-process issuer), the
+  # `zone` (derives the control + data hosts), and the `control_plane`
+  # (project-JWS create/inspect/destroy at api.<zone>). Built by
+  # PineSandbox::Client — not a public constructor.
+  class Connection
+    attr_reader :zone, :control_plane, :attach_provider, :clock
+
+    # `clock` paces every wait the Computer and its data-plane client make.
+    def initialize(zone:, control_plane:, attach_provider:, clock: PineSandbox::SYSTEM_CLOCK)
+      raise ArgumentError, "attach_provider required (mints the per-attach bind_token + broker_grant)" unless attach_provider
+      raise ArgumentError, "zone required (a PineSandbox::Zone)" unless zone.is_a?(PineSandbox::Zone)
+      raise ArgumentError, "control_plane required" unless control_plane
+
+      @attach_provider = attach_provider
+      @zone = zone
+      @control_plane = control_plane
+      @clock = clock
+    end
+  end
+end

data/lib/pinesandbox/control_events.rb

@@ -0,0 +1,156 @@
+require "json"
+require "time"
+
+module PineSandbox
+  # Typed events delivered by `Session#control_events(&block)`. Each
+  # struct corresponds to one of the four canonical v1 SSE event types:
+  #
+  #   - controller_changed   → ControllerChanged
+  #   - idle_changed         → IdleChanged
+  #   - handoff_completed    → HandoffCompleted
+  #   - handoff_failed       → HandoffFailed
+  #
+  # `idle_warning` (IdleWarning) is decoded too, should the Computer emit it.
+  #
+  # The block sees ONE typed struct per event. Unknown event types are
+  # dropped silently — clients should add new types via this catalog
+  # before stable consumers exist (SSE protocol contract).
+  #
+  # All structs carry `id` (the SSE `id:` field, monotonic uint64 per
+  # session) so callers can stash the last-seen ID for reconnect, and `type`
+  # (the SSE event name).
+  module ControlEvents
+    ControllerChanged = Struct.new(:id, :session_name, :controller, :epoch, :trigger,
+                                   :current_human_session, keyword_init: true) do
+      def type = "controller_changed"
+    end
+    # The person's idle deadline or pause changed. `idle_deadline` is a Time,
+    # or nil while the idle timer is paused.
+    IdleChanged = Struct.new(:id, :session_name, :epoch, :idle_deadline, :idle_paused,
+                             :sub_operations, keyword_init: true) do
+      def type = "idle_changed"
+    end
+    IdleWarning = Struct.new(:id, :session_name, :expires_in_seconds, keyword_init: true) do
+      def type = "idle_warning"
+    end
+    HandoffCompleted = Struct.new(:id, :session_name, :handoff_id, keyword_init: true) do
+      def type = "handoff_completed"
+    end
+    HandoffFailed = Struct.new(:id, :session_name, :handoff_id, :reason, :problem,
+                                keyword_init: true) do
+      def type = "handoff_failed"
+    end
+
+    # decode_event parses one SSE frame's (event_type, id, data_json)
+    # tuple into the matching typed struct. Returns nil on unknown event
+    # type or invalid JSON — the caller advances to the next frame.
+    def self.decode_event(event_type, id, data_json)
+      data =
+        begin
+          data_json.is_a?(Hash) ? data_json : JSON.parse(data_json.to_s)
+        rescue JSON::ParserError
+          return nil
+        end
+
+      case event_type
+      when "controller_changed"
+        ControllerChanged.new(
+          id: id,
+          session_name: data["session_name"],
+          controller: data["controller"],
+          epoch: data["epoch"],
+          trigger: data["trigger"],
+          current_human_session: data["current_human_session"]
+        )
+      when "idle_changed"
+        IdleChanged.new(
+          id: id,
+          session_name: data["session_name"],
+          epoch: data["epoch"],
+          idle_deadline: parse_time(data["idle_deadline"]),
+          idle_paused: data["idle_paused"] == true,
+          sub_operations: Array(data["sub_operations"])
+        )
+      when "idle_warning"
+        IdleWarning.new(
+          id: id,
+          session_name: data["session_name"],
+          expires_in_seconds: data["expires_in_seconds"]
+        )
+      when "handoff_completed"
+        HandoffCompleted.new(
+          id: id,
+          session_name: data["session_name"],
+          handoff_id: data["handoff_id"]
+        )
+      when "handoff_failed"
+        HandoffFailed.new(
+          id: id,
+          session_name: data["session_name"],
+          handoff_id: data["handoff_id"],
+          reason: data["reason"],
+          problem: data["problem"]
+        )
+      end
+    end
+
+    def self.parse_time(value)
+      return nil unless value.is_a?(String) && !value.empty?
+
+      Time.iso8601(value)
+    rescue ArgumentError
+      nil
+    end
+    private_class_method :parse_time
+  end
+
+  # ControlEventStreamParser parses the v1 SSE byte stream
+  # (`id:\nevent:\ndata:\n\n`) into typed ControlEvents structs. Unlike
+  # Services::EventStreamParser, this parser is focused on the v1
+  # control surface: every emitted event has an `event:` discriminator,
+  # the JSON `data` payload has NO `type` field (the SSE `event:` IS
+  # the type), and ID is decimal-encoded uint64.
+  #
+  # Use:
+  #   parser = ControlEventStreamParser.new
+  #   parser.feed(chunk) { |evt| ... }   # multiple calls as chunks arrive
+  #   parser.finish                      # end of stream: drop a cut-off block
+  #
+  # The parser is stateful per-stream; instantiate a fresh one on
+  # reconnect.
+  class ControlEventStreamParser
+    def initialize
+      @frames = SseFrameParser.new
+    end
+
+    # Feed a chunk; yields a typed ControlEvents::* struct per decoded frame.
+    # Framing is delegated to the single SseFrameParser; this class owns only
+    # the control-event DECODING (event-name + id + payload → typed struct).
+    def feed(chunk, &block)
+      @frames.feed(chunk) { |frame| emit(frame, &block) }
+    end
+
+    # The end of the stream: a trailing block missing its blank-line
+    # terminator was cut off and is dropped.
+    def finish(&_block)
+      @frames.finish
+    end
+
+    private
+
+    # Decode one framed event into a typed struct and hand it to the caller.
+    # Unknown event types decode to nil (forward-compat) and are dropped; a
+    # non-integer id decodes to a nil id.
+    def emit(frame, &block)
+      typed = ControlEvents.decode_event(frame.event, parse_id(frame.id), frame.data)
+      block.call(typed) if typed && block
+    end
+
+    def parse_id(s)
+      return nil if s.nil?
+      Integer(s, 10)
+    rescue ArgumentError
+      nil
+    end
+  end
+end