pinesandbox 0.0.1 → 0.3.18

data/lib/pinesandbox/attach_credentials_source.rb

@@ -0,0 +1,392 @@
+require "faraday"
+require "json"
+require_relative "errors"
+
+module PineSandbox
+  # The pk_-backed attach-credential provider — the DEFAULT attach path
+  # (AUTH_REDESIGN: portal-as-issuer). Exchanges the project client key at the
+  # portal for per-attach credentials:
+  #
+  #   * GET /v1/locations                               — project-visible
+  #     country discovery.
+  #   * POST /v1/computers                                — optional legacy
+  #     pre-registration helper. Normal attach does not require it.
+  #   * POST /v1/computers/:computer_id/attach-credentials — body carries the
+  #     runtime coordinates {pod_uid, coord_boot_id}; returns {bind_token,
+  #     broker_grant, key_assertion, binding_revision}. The portal authenticates
+  #     the pk_ and atomically creates/rechecks its minimal authorization row,
+  #     advances the key floor, supersedes the prior binding, and mints.
+  #   * DELETE /v1/computers/:computer_id                 — permanent delete.
+  #     204 for deleted, already deleted, unknown, and cross-project ids alike.
+  #
+  # This source caches nothing. Computer#run_bind calls it exactly once for a
+  # sandbox, then convergence retries re-send the held envelope verbatim
+  # (the bind is idempotent on jti + ciphertext). A runtime-identity shift
+  # requires a fresh sandbox; it never authorizes the same sandbox twice.
+  # The pk_ never appears in #inspect.
+  class AttachCredentialsSource
+    REGISTER_PATH = "/v1/computers"
+    LOCATIONS_PATH = "/v1/locations"
+
+    def initialize(api_key:, host:, protocol: "https",
+                   open_timeout: 5, request_timeout: 30, connection: nil, gateway_url: nil)
+      raise ArgumentError, "api_key required (a pk_ client key)" if api_key.to_s.empty?
+
+      @api_key = api_key.to_s
+      @host = host.to_s
+      @protocol = protocol
+      @gateway_url = gateway_url
+      @open_timeout = open_timeout
+      @request_timeout = request_timeout
+      @connection = connection
+    end
+
+    # Register `computer_id` into the portal ownership registry (idempotent —
+    # re-registering the same id for the same project is a no-op success).
+    # Returns the parsed registration body.
+    def register_computer(computer_id, location: nil)
+      raise ArgumentError, "computer_id required" if computer_id.to_s.empty?
+
+      body = { computer_id: computer_id.to_s }
+      body[:location] = normalize_location(location) if location
+      resp = post(REGISTER_PATH, json: body, op: "computer registration")
+      case resp.status
+      when 200, 201
+        parse_json(resp)
+      when 409, 422
+        raise ComputerRegistrationError.new(
+          error_message(resp, "computer registration refused (#{resp.status})"),
+          status: resp.status, body: resp.body, request_id: request_id(resp), op: http_op(resp)
+        )
+      else
+        raise_generic(resp, "computer registration")
+      end
+    end
+
+    # Return the project-visible country catalog and server-owned default. This
+    # is inventory discovery only; a real route is still qualified and
+    # activated when the Computer binds.
+    def available_locations
+      resp = get(LOCATIONS_PATH, op: "location discovery")
+      raise_location_error(resp) unless resp.status == 200
+
+      payload = parse_json(resp)
+      locations = payload["locations"]
+      default_location = payload["default_location"]
+      valid = locations.is_a?(Array) &&
+              locations.all? { |location| response_location?(location) } &&
+              locations.map { |location| location["country"] }.uniq.length == locations.length &&
+              response_location?(default_location)
+      unless valid
+        raise LocationDiscoveryError.new(
+          "location discovery response was malformed",
+          status: 200, body: resp.body, request_id: request_id(resp), op: http_op(resp)
+        )
+      end
+      payload
+    end
+
+    def project_policy
+      resp = get("/v1/project-policy", op: "project policy")
+      raise PortalError.new(error_message(resp, "Project policy unavailable"), **error_attributes(resp)) unless resp.status == 200
+
+      payload = parse_json(resp)
+      unless payload.is_a?(Hash) && payload.key?("lifecycle") && payload.key?("max_concurrent_computers")
+        raise PortalError.new("Invalid project policy response", **error_attributes(resp))
+      end
+      payload
+    end
+
+    # One authorization-registry read before Start; never a runtime status poll.
+    def current_binding(computer_id)
+      resp = get("#{REGISTER_PATH}/#{computer_id}", op: "computer binding lookup")
+      if resp.status == 404
+        raise UnknownComputerError.new("Computer not found", **error_attributes(resp))
+      end
+      raise_generic(resp, "computer binding lookup") unless resp.status == 200
+      payload = parse_json(resp)
+      unless payload["computer_id"] == computer_id && payload["binding_revision"].is_a?(Integer) && payload["binding_revision"] >= 0 &&
+             (payload["sandbox_id"].nil? || payload["sandbox_id"].is_a?(String))
+        raise AttachCredentialsError.new("computer binding response was malformed", **error_attributes(resp))
+      end
+      payload
+    end
+
+    # Permanently delete `computer_id`. The portal tombstones it at once (no
+    # further attach, renewal, or lease refresh), destroys its bound sandboxes
+    # asynchronously, keeps saved browser state for 24 hours before purging it,
+    # and never accepts the id again. Idempotent and non-disclosing: an unknown,
+    # already-deleted, or cross-project id is the same 204. Returns true.
+    def delete_computer(computer_id)
+      raise ArgumentError, "computer_id required" if computer_id.to_s.empty?
+
+      resp = delete("#{REGISTER_PATH}/#{computer_id}", op: "computer deletion")
+      case resp.status
+      when 204
+        true
+      when 422
+        raise ComputerDeletionError.new(
+          error_message(resp, "computer deletion refused: malformed computer_id #{computer_id}"),
+          **error_attributes(resp)
+        )
+      else
+        raise_generic(resp, "computer deletion", forbidden: "project or key may not delete computers")
+      end
+    end
+
+    # Mint the per-attach credentials for one runtime + boot. `sandbox_id` is the
+    # provisioned sandbox this attach targets — the portal records the
+    # sandbox→computer attribution at mint (its renewal gate keys off it).
+    # Returns a Hash with string keys: "bind_token", "broker_grant",
+    # "key_assertion", "binding_revision", and the effective "location"
+    # (plus expiry metadata).
+    # `pk_computer` (base64url raw X25519 public key) + `key_generation` drive
+    # the v3 persistent attach: the portal advances its per-Computer key floor
+    # and returns the signed "key_assertion". They are OPTIONAL — an ephemeral
+    # Computer (access-lease only, no persistence) omits both, and the portal
+    # then mints an access-lease-only binding with no key_assertion.
+    def credentials(computer_id:, pod_uid:, coord_boot_id:, sandbox_id:,
+                    expected_binding_revision:, idempotency_key:,
+                    pk_computer: nil, key_generation: nil, location: nil)
+      raise ArgumentError, "computer_id required" if computer_id.to_s.empty?
+      raise ArgumentError, "pod_uid required" if pod_uid.to_s.empty?
+      raise ArgumentError, "coord_boot_id required" if coord_boot_id.to_s.empty?
+      raise ArgumentError, "sandbox_id required" if sandbox_id.to_s.empty?
+      # pk_computer/key_generation are the persistent-attach pair: BOTH present
+      # (v3) or BOTH absent (ephemeral). EXACTLY ONE is a malformed persistent
+      # request — reject it locally instead of silently dropping the field and
+      # registering the Computer as ephemeral. When present, the generation must
+      # be positive.
+      if pk_computer.to_s.empty? != key_generation.to_s.empty?
+        raise ArgumentError, "pk_computer and key_generation must be provided together"
+      end
+      raise ArgumentError, "key_generation must be positive" if !pk_computer.to_s.empty? && !key_generation.to_i.positive?
+      raise ArgumentError, "expected_binding_revision must be non-negative" if expected_binding_revision.to_i.negative?
+      raise ArgumentError, "idempotency_key required" if idempotency_key.to_s.empty?
+
+      body = {
+        pod_uid: pod_uid,
+        coord_boot_id: coord_boot_id,
+        sandbox_id: sandbox_id
+      }
+      body[:location] = normalize_location(location) if location
+      if pk_computer.to_s.empty?
+        # Ephemeral: no capture identity, and signal the mode so the portal
+        # lazily creates a new Computer row as ephemeral.
+        body[:persistence_mode] = "ephemeral"
+      else
+        body[:pk_computer] = pk_computer
+        body[:key_generation] = key_generation
+      end
+      body[:expected_binding_revision] = expected_binding_revision
+      resp = post(
+        "#{REGISTER_PATH}/#{computer_id}/attach-credentials", json: body,
+        op: "attach-credentials", headers: { "Idempotency-Key" => idempotency_key }
+      )
+      case resp.status
+      when 200
+        parsed = parse_json(resp)
+        begin
+          committed_revision = Integer(parsed["binding_revision"])
+        rescue ArgumentError, TypeError
+          committed_revision = -1
+        end
+        if committed_revision <= expected_binding_revision.to_i
+          raise AttachCredentialsError.new(
+            "attach-credentials response missing an advancing binding revision",
+            status: 200, body: resp.body, request_id: request_id(resp), op: http_op(resp)
+          )
+        end
+        # An advancing revision means Portal committed. Return the complete
+        # receipt to Computer, which records that revision before validating
+        # the remaining v3 fields.
+        parsed
+      when 404
+        raise UnknownComputerError.new(
+          error_message(resp, "unknown, deleted, or cross-project computer_id #{computer_id}"),
+          **error_attributes(resp)
+        )
+      when 412
+        problem = parse_json(resp)
+        raise BindingRevisionConflictError.new(
+          binding_conflict_message(
+            error_message(resp, "binding revision changed; reload and adopt the winning binding"),
+            problem["current_binding_revision"], problem["current_sandbox_id"]
+          ),
+          current_binding_revision: problem["current_binding_revision"],
+          current_runtime_id: problem["current_sandbox_id"],
+          **error_attributes(resp)
+        )
+      else
+        raise_generic(resp, "attach-credentials mint")
+      end
+    end
+
+    def inspect
+      "#<PineSandbox::AttachCredentialsSource host=#{@host.inspect} [pk_ redacted]>"
+    end
+    alias_method :to_s, :inspect
+
+    private
+
+    def normalize_location(value)
+      unless value.is_a?(Hash)
+        raise ArgumentError, "location must be a Hash with country: or mode: \"direct\""
+      end
+      normalized = value.transform_keys(&:to_s)
+      return { mode: "direct" } if normalized == { "mode" => "direct" }
+      unless normalized.keys == [ "country" ] &&
+             normalized["country"].is_a?(String) &&
+             normalized["country"].match?(/\A[A-Z]{2}\z/)
+        raise ArgumentError, "location must contain an ISO alpha-2 country or mode: \"direct\", exclusively"
+      end
+      { country: normalized.fetch("country") }
+    end
+
+    def response_location?(value)
+      value.is_a?(Hash) && value["country"].is_a?(String) &&
+        value["country"].match?(/\A[A-Z]{2}\z/)
+    end
+
+    def raise_location_error(resp)
+      if resp.status == 403
+        raise ProjectAccessDenied.new(
+          error_message(resp, "project or key may not discover locations"),
+          **error_attributes(resp)
+        )
+      end
+      message = error_message(resp, "portal location discovery failed (#{resp.status})")
+      if resp.status == 401
+        message = "invalid project client key (unknown or revoked pk_): #{message}"
+      end
+      raise LocationDiscoveryError.new(
+        message,
+        **error_attributes(resp)
+      )
+    end
+
+    # 403 is the one status broken out of the AttachCredentialsError family — the
+    # project/key/computer may not mint now (ProjectAccessDenied). A bad key (401), a rate
+    # limit (429), and server errors all stay AttachCredentialsError (with #status) so a
+    # `rescue AttachCredentialsError` around the attach call keeps catching them; callers
+    # distinguish a bad key by #status == 401.
+    def raise_generic(resp, label,
+                      forbidden: "project or key may not mint attach credentials (scope, project status, or computer status)")
+      if resp.status == 403
+        raise ProjectAccessDenied.new(
+          error_message(resp, forbidden),
+          **error_attributes(resp)
+        )
+      end
+      default =
+        case resp.status
+        when 401 then "invalid or unknown project client key"
+        when 429 then "portal rate-limited the #{label}"
+        else "portal #{label} failed (#{resp.status})"
+        end
+      raise AttachCredentialsError.new(error_message(resp, default), **error_attributes(resp))
+    end
+
+    # "<METHOD> <path>" off the Faraday response env — WHICH portal operation failed (the
+    # path carries the computer_id for the computer-scoped mints, so it names WHICH Computer).
+    # nil when the env/url is unavailable (a diagnostic detail must never mask the real error).
+    def http_op(resp)
+      env = resp.respond_to?(:env) ? resp.env : nil
+      return nil unless env && env.method
+
+      url = env.url
+      path = url.respond_to?(:path) ? url.path : url.to_s
+      "#{env.method.to_s.upcase} #{path}"
+    rescue StandardError
+      nil
+    end
+
+    def post(path, json:, op:, headers: {})
+      request(:post, path, op: op) do |req|
+        req.headers["Authorization"] = "Bearer #{@api_key}"
+        req.headers["Accept"] = "application/json"
+        req.headers["Content-Type"] = "application/json"
+        headers.each { |key, value| req.headers[key] = value }
+        req.body = json.to_json
+      end
+    end
+
+    def get(path, op:)
+      request(:get, path, op: op) do |req|
+        req.headers["Authorization"] = "Bearer #{@api_key}"
+        req.headers["Accept"] = "application/json"
+      end
+    end
+
+    def delete(path, op:)
+      request(:delete, path, op: op) do |req|
+        req.headers["Authorization"] = "Bearer #{@api_key}"
+        req.headers["Accept"] = "application/json"
+      end
+    end
+
+    def request(method, path, op:)
+      connection.public_send(method, path) { |req| yield req }
+    rescue Faraday::TimeoutError => e
+      raise PineSandbox::TimeoutError,
+            PineSandbox.with_context(
+              "portal #{op} call timed out: #{e.message}",
+              op: "#{method.to_s.upcase} #{path.split('?').first}"
+            )
+    rescue Faraday::ConnectionFailed => e
+      raise PineSandbox::ConnectionError,
+            PineSandbox.with_context(
+              "portal #{op} connection failed: #{e.message}",
+              op: "#{method.to_s.upcase} #{path.split('?').first}"
+            )
+    end
+
+    def request_id(resp)
+      resp.headers["x-request-id"] || resp.headers["X-Request-Id"]
+    end
+
+    # The attach revision is a fence against two live attaches of one
+    # Computer, so the SDK never retries past it; the message says what to do.
+    def binding_conflict_message(message, current_revision, current_runtime_id)
+      return message unless current_revision.is_a?(Integer)
+
+      holder = current_runtime_id.to_s.empty? ? "" : " (runtime #{current_runtime_id})"
+      "#{message}. Another start changed the Computer binding#{holder}. " \
+        "Do not retry automatically. Check the current runtime before starting again."
+    end
+
+    def error_message(resp, default)
+      body = parse_json(resp)
+      msg = body["detail"] || body["message"] || body["error"]
+      msg.to_s.empty? ? default : msg.to_s
+    rescue StandardError
+      default
+    end
+
+    def error_attributes(resp)
+      problem = parse_json(resp)
+      body_request_id = problem["request_id"].to_s
+      {
+        status: resp.status, body: resp.body,
+        request_id: body_request_id.empty? ? request_id(resp) : body_request_id,
+        op: http_op(resp), problem_type: problem["type"], reason: problem["reason"]
+      }
+    end
+
+    def parse_json(resp)
+      return resp.body if resp.body.is_a?(Hash)
+      return {} if resp.body.to_s.empty?
+
+      JSON.parse(resp.body)
+    rescue JSON::ParserError
+      {}
+    end
+
+    def connection
+      @connection ||= Zone.faraday(scheme: @protocol, host: @host, gateway_url: @gateway_url) do |f|
+        f.options.open_timeout = @open_timeout
+        f.options.timeout = @request_timeout
+      end
+    end
+  end
+end

data/lib/pinesandbox/author_terminal_translator.rb

@@ -0,0 +1,96 @@
+require_relative "errors"
+
+module PineSandbox
+  # Maps a streaming authoring run's terminal Result (the last event of
+  # /v2/sessions/{name}/skills/author/{id}/events) into the {LearnResult} /
+  # {TeachResult} return shapes of the blocking Session#learn / Session#teach.
+  #
+  # The terminal Result's `terminal_reason` is one of the AUTHOR_TERMINAL_*
+  # values below; the optional `author` object carries the typed
+  # authoring outcome.
+  module AuthorTerminalTranslator
+    AUTHOR_TERMINAL_DRAFT_REGISTERED       = "draft_registered".freeze
+    AUTHOR_TERMINAL_CLARIFICATION_REQUEST  = "clarification_requested".freeze
+    AUTHOR_TERMINAL_NOT_REUSABLE           = "not_reusable".freeze
+    AUTHOR_TERMINAL_REGISTRATION_FAILED    = "registration_failed".freeze
+    AUTHOR_TERMINAL_CANCELED               = "canceled".freeze
+    AUTHOR_TERMINAL_FAILED                 = "failed".freeze
+    # Terminal reason when the Computer's services restarted while the run
+    # was in flight. Surfaced to the caller as an Error so they can retry —
+    # the authoring itself didn't fail; the run got interrupted.
+    AUTHOR_TERMINAL_COORDINATOR_RESTARTED  = "coordinator_restarted".freeze
+
+    module_function
+
+    # to_learn_result translates the terminal event to the legacy /learn body.
+    # Self-Learn has no clarification round (an ambiguous run reports false +
+    # the caller runs Teach instead), so clarification_requested folds into
+    # learned:false here.
+    def to_learn_result(terminal)
+      raise PineSandbox::Error, "author run produced no terminal event" if terminal.nil?
+
+      result = terminal["payload"] || {}
+      reason = result["terminal_reason"]
+      summary = result["summary"]
+      author = result["author"].is_a?(Hash) ? result["author"] : {}
+
+      case reason
+      when AUTHOR_TERMINAL_DRAFT_REGISTERED
+        draft = author["draft"]
+        raise PineSandbox::Error, "author run draft_registered without draft metadata" if draft.nil?
+        { "learned" => true, "draft" => draft }
+      when AUTHOR_TERMINAL_CLARIFICATION_REQUEST
+        { "learned" => false, "reason" => "the run was too ambiguous to author a reliable skill — teach it instead" }
+      when AUTHOR_TERMINAL_NOT_REUSABLE
+        { "learned" => false, "reason" => summary || "the navigation is not a reusable skill" }
+      when AUTHOR_TERMINAL_REGISTRATION_FAILED, AUTHOR_TERMINAL_CANCELED, AUTHOR_TERMINAL_FAILED, "storage_exhausted"
+        raise PineSandbox::Error, "author run #{reason}: #{summary}"
+      when AUTHOR_TERMINAL_COORDINATOR_RESTARTED
+        raise PineSandbox::Error,
+              "author run interrupted because the Computer's services restarted — retry the learn call"
+      else
+        raise PineSandbox::Error, "unknown author terminal_reason: #{reason}"
+      end
+    end
+
+    # to_teach_result translates the terminal event to the legacy /teach body.
+    # Teach DOES support clarification — the legacy contract carries the
+    # questions and the handoff_id on `needs_clarification: true`. The handoff_id
+    # comes from the 202 echo (passed in) since the legacy /teach response also
+    # echoed it on both success and clarification.
+    def to_teach_result(terminal, handoff_id:)
+      raise PineSandbox::Error, "author run produced no terminal event" if terminal.nil?
+
+      result = terminal["payload"] || {}
+      reason = result["terminal_reason"]
+      summary = result["summary"]
+      author = result["author"].is_a?(Hash) ? result["author"] : {}
+
+      case reason
+      when AUTHOR_TERMINAL_DRAFT_REGISTERED
+        draft = author["draft"]
+        raise PineSandbox::Error, "author run draft_registered without draft metadata" if draft.nil?
+        { "taught" => true, "handoff_id" => handoff_id, "draft" => draft }
+      when AUTHOR_TERMINAL_CLARIFICATION_REQUEST
+        questions = author["questions"] || []
+        echoed_handoff = author["handoff_id"] || handoff_id
+        {
+          "taught" => false,
+          "needs_clarification" => true,
+          "questions" => questions,
+          "handoff_id" => echoed_handoff
+        }
+      when AUTHOR_TERMINAL_NOT_REUSABLE
+        { "taught" => false, "reason" => summary || "the demonstration is not a reusable skill" }
+      when AUTHOR_TERMINAL_REGISTRATION_FAILED, AUTHOR_TERMINAL_CANCELED, AUTHOR_TERMINAL_FAILED, "storage_exhausted"
+        raise PineSandbox::Error, "author run #{reason}: #{summary}"
+      when AUTHOR_TERMINAL_COORDINATOR_RESTARTED
+        raise PineSandbox::Error,
+              "author run interrupted because the Computer's services restarted — retry the teach call"
+      else
+        raise PineSandbox::Error, "unknown author terminal_reason: #{reason}"
+      end
+    end
+
+  end
+end

data/lib/pinesandbox/bind_hpke.rb

@@ -0,0 +1,54 @@
+require "hpke"
+require "openssl"
+
+module PineSandbox
+  # BindHPKE seals the bind payload (computer_key + broker_grant) to the
+  # Computer's per-process ephemeral X25519 public key using RFC 9180
+  # HPKE in this fixed suite:
+  #
+  #   KEM  = DHKEM(X25519, HKDF-SHA256)   (0x0020)
+  #   KDF  = HKDF-SHA256                   (0x0001)
+  #   AEAD = ChaCha20-Poly1305             (0x0003)
+  #
+  # The wire form is `enc(32 bytes) || aead_ciphertext`.
+  module BindHPKE
+    module_function
+
+    # info binds the sealed payload to the receiving process identity so a
+    # ciphertext sealed for one runtime/boot cannot be opened by another.
+    # MUST byte-match the receiver's info string.
+    #
+    # @param pod_uid [String]
+    # @param coord_boot_id [String]
+    # @return [String] ASCII info string.
+    def info(pod_uid, coord_boot_id)
+      "pine.bind.v1|#{pod_uid}|#{coord_boot_id}"
+    end
+
+    # restore_info is the two-round v3 restore's round-2 domain: the
+    # integrator-unwrapped component secrets sealed back to the same runtime
+    # key. Same suite, DISTINCT domain — a bind ciphertext can never be
+    # replayed as a secrets payload or vice versa. MUST byte-match the
+    # receiver's restore info string.
+    def restore_info(pod_uid, coord_boot_id)
+      "pine.bind.restore.v1|#{pod_uid}|#{coord_boot_id}"
+    end
+
+    # seal encrypts plaintext to the recipient's raw 32-byte X25519 public
+    # key. The AAD is fixed empty (the portal attach path carries no nonce —
+    # payload-to-runtime binding lives in the info string).
+    #
+    # @param recipient_pub_raw [String] 32 raw bytes (NOT base64).
+    # @param plaintext [String] bytes to seal.
+    # @param info [String] context string from #info.
+    # @return [String] HPKE wire bytes: enc(32) || ciphertext.
+    def seal(recipient_pub_raw, plaintext, info)
+      pk_r = OpenSSL::PKey.new_raw_public_key("X25519", recipient_pub_raw)
+      hpke = HPKE.new(HPKE::DHKEM_X25519_HKDF_SHA256, HPKE::HKDF_SHA256, HPKE::CHACHA20_POLY1305)
+      res = hpke.setup_base_s(pk_r, info.b)
+      # hpke gem arg order is (aad, plaintext) — AAD first; ours is empty.
+      ct = res[:context_s].seal("", plaintext)
+      res[:enc] + ct
+    end
+  end
+end

data/lib/pinesandbox/capture_keypair.rb

@@ -0,0 +1,43 @@
+require_relative "state_hpke"
+
+module PineSandbox
+  # CaptureKeypair is the integrator's asymmetric state-encryption identity
+  # (asymmetric component envelope v3): state is sealed to +pk+ on the platform —
+  # which never holds +sk+ — and restoring it requires this SDK to unwrap
+  # the per-component secrets during the bind (the two-round restore).
+  # PERSIST both halves; retain SUPERSEDED generations until their state has
+  # been re-sealed (a restore of pre-rotation state needs the old sk).
+  class CaptureKeypair
+    attr_reader :generation, :pk, :sk
+
+    # @param generation [Integer] monotonic keypair generation (the portal
+    #   records a per-Computer floor; a rotation submits generation+1).
+    # @param pk [String] 32 raw X25519 public-key bytes.
+    # @param sk [String] 32 raw X25519 private-key bytes.
+    def initialize(generation:, pk:, sk:)
+      raise ArgumentError, "capture keypair generation must be positive" unless generation.is_a?(Integer) && generation.positive?
+      raise ArgumentError, "capture keypair halves must be 32 bytes" unless pk.to_s.bytesize == 32 && sk.to_s.bytesize == 32
+
+      @generation = generation
+      @pk = pk.dup.freeze
+      @sk = sk.dup.freeze
+    end
+
+    # Mint a fresh capture keypair offline.
+    def self.generate(generation:)
+      pk, sk = StateHPKE.generate_keypair
+      new(generation: generation, pk: pk, sk: sk)
+    end
+
+    # The canonical public-key fingerprint (hex sha256) the platform binds
+    # into every envelope sealed to this keypair.
+    def fingerprint
+      StateHPKE.fingerprint(@pk)
+    end
+
+    def inspect
+      "#<PineSandbox::CaptureKeypair generation=#{@generation} pk=#{fingerprint[0, 16]} sk=[redacted]>"
+    end
+    alias_method :to_s, :inspect
+  end
+end