robocap-decryption-sdk 1.0.0

data/lib/robocap/sdk/key_vault.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'openssl'
+require 'pathname'
+require_relative 'config'
+require_relative 'errors'
+require_relative 'rsa_key_meta'
+require_relative 'rsa_oaep'
+require_relative 'vault_layout'
+
+module Robocap
+  module SDK
+    CekTrialUnwrapResult = Data.define(:cek, :rsa_key_version)
+
+    class KeyVault
+      RSA_VERSION_DIR_RE = /\Av(\d+)\z/
+
+      def initialize(sdk_root)
+        @sdk_root  = Pathname(sdk_root)
+        @keys_root = Config.keys_vault_root(@sdk_root)
+      end
+
+      attr_reader :sdk_root
+
+      def customer_root(customer_id)
+        Config.validate_customer_id!(customer_id)
+        @keys_root.join(customer_id)
+      end
+
+      def rsa_version_dir(customer_id, version)
+        customer_root(customer_id).join('rsa', "v#{version}")
+      end
+
+      def public_pem(customer_id, version)
+        rsa_version_dir(customer_id, version).join('public.pem')
+      end
+
+      def private_pem(customer_id, version)
+        rsa_version_dir(customer_id, version).join('private.pem')
+      end
+
+      def rsa_meta_path(customer_id, version)
+        rsa_version_dir(customer_id, version).join('meta.json')
+      end
+
+      def self.public_pem_path_for_dir(key_dir)
+        Pathname(key_dir).join('public.pem')
+      end
+
+      def self.private_pem_path_for_dir(key_dir)
+        Pathname(key_dir).join('private.pem')
+      end
+
+      def rsa_dir(customer_id)
+        customer_root(customer_id).join('rsa')
+      end
+
+      def exists_customer?(customer_id)
+        customer_root(customer_id).directory?
+      end
+
+      def list_rsa_versions(customer_id)
+        rsa_dir = customer_root(customer_id).join('rsa')
+        return [] unless rsa_dir.directory?
+        rsa_dir.children.each_with_object([]) do |child, acc|
+          next unless child.directory?
+          m = RSA_VERSION_DIR_RE.match(child.basename.to_s)
+          acc << m[1].to_i if m
+        end.sort
+      end
+
+      def get_latest_rsa_version(customer_id)
+        versions = list_rsa_versions(customer_id)
+        if versions.empty?
+          raise Error.new(
+            code: ErrorCode::ERR_RSA_NOT_IMPORTED,
+            message: "No RSA keys imported for customer #{customer_id}",
+          )
+        end
+        versions.max
+      end
+
+      def get_public_key(customer_id, version)
+        path = public_pem(customer_id, version)
+        unless path.file?
+          raise Error.new(
+            code: ErrorCode::ERR_RSA_VERSION_MISSING,
+            message: "RSA public key v#{version} not found for #{customer_id}",
+          )
+        end
+        load_public_key_from(path)
+      end
+
+      def get_private_key(customer_id, version)
+        path = private_pem(customer_id, version)
+        unless path.file?
+          raise Error.new(
+            code: ErrorCode::ERR_RSA_VERSION_MISSING,
+            message: "RSA private key v#{version} not found for #{customer_id}",
+          )
+        end
+        load_private_key_from(path)
+      end
+
+      def get_latest_public_key(customer_id)
+        get_public_key(customer_id, get_latest_rsa_version(customer_id))
+      end
+
+      def load_rsa_meta(customer_id, version)
+        path = rsa_meta_path(customer_id, version)
+        unless path.file?
+          raise Error.new(
+            code: ErrorCode::ERR_RSA_VERSION_MISSING,
+            message: "RSA meta v#{version} not found for #{customer_id}",
+          )
+        end
+        RsaKeyMeta.from_json(path.read(encoding: 'UTF-8'))
+      end
+
+      def import_rsa_version(customer_id:, public_pem:, private_pem:, meta:)
+        Config.validate_customer_id!(customer_id)
+        version = meta.rsa_key_version
+        pub_key  = OpenSSL::PKey::RSA.new(public_pem)
+        priv_key = OpenSSL::PKey::RSA.new(private_pem)
+
+        if pub_key.private? || !priv_key.private?
+          raise Error.new(code: ErrorCode::ERR_RSA_IMPORT_INVALID, message: 'Invalid RSA key pair PEM')
+        end
+
+        unless Config::RSA_BITS_ALLOWED.include?(meta.rsa_bits)
+          raise Error.new(
+            code: ErrorCode::ERR_INVALID_RSA_BITS,
+            message: "RSA rsa_bits must be one of #{Config::RSA_BITS_ALLOWED}",
+          )
+        end
+
+        actual_bits_pub  = pub_key.n.num_bits
+        actual_bits_priv = priv_key.n.num_bits
+        if actual_bits_pub != meta.rsa_bits || actual_bits_priv != meta.rsa_bits
+          raise Error.new(
+            code: ErrorCode::ERR_INVALID_RSA_BITS,
+            message: "RSA keys must be #{meta.rsa_bits} bits",
+          )
+        end
+
+        if pub_key.n != priv_key.n || pub_key.e != priv_key.e
+          raise Error.new(
+            code: ErrorCode::ERR_RSA_IMPORT_INVALID,
+            message: 'Public and private key do not match',
+          )
+        end
+
+        dir = rsa_version_dir(customer_id, version)
+        if dir.exist?
+          raise Error.new(
+            code: ErrorCode::ERR_CUSTOMER_ALREADY_EXISTS,
+            message: "RSA version v#{version} already exists for #{customer_id}",
+          )
+        end
+
+        VaultLayout.ensure_private_dir(dir)
+        VaultLayout.atomic_write_bytes(self.public_pem(customer_id, version),  public_pem)
+        VaultLayout.atomic_write_bytes(self.private_pem(customer_id, version), private_pem)
+        VaultLayout.atomic_write_text(rsa_meta_path(customer_id, version), meta.to_pretty_json)
+        VaultLayout.ensure_private_dir(customer_root(customer_id))
+        version
+      end
+
+      def delete_rsa_version(customer_id, version)
+        Config.validate_customer_id!(customer_id)
+        unless exists_customer?(customer_id)
+          raise Error.new(
+            code: ErrorCode::ERR_CUSTOMER_NOT_FOUND,
+            message: "Customer not found: #{customer_id}",
+          )
+        end
+        dir = rsa_version_dir(customer_id, version)
+        unless dir.directory?
+          raise Error.new(
+            code: ErrorCode::ERR_RSA_VERSION_MISSING,
+            message: "RSA version v#{version} not found for #{customer_id}",
+          )
+        end
+        begin
+          FileUtils.remove_entry_secure(dir)
+        rescue SystemCallError => exc
+          raise Error.new(
+            code: ErrorCode::ERR_VAULT_IO,
+            message: "Failed to delete RSA version v#{version}: #{exc.message}",
+          )
+        end
+      end
+
+      def list_rsa_key_dirs(customer_id)
+        Config.validate_customer_id!(customer_id)
+        dir = rsa_dir(customer_id)
+        return [] unless dir.directory?
+        dir.children.sort_by { |c| c.basename.to_s.downcase }.filter_map do |child|
+          next nil unless valid_rsa_key_dir?(child)
+          Pathname(child.realpath)
+        end
+      end
+
+      def delete_rsa_key_dir(customer_id, key_dir)
+        Config.validate_customer_id!(customer_id)
+        unless exists_customer?(customer_id)
+          raise Error.new(
+            code: ErrorCode::ERR_CUSTOMER_NOT_FOUND,
+            message: "Customer not found: #{customer_id}",
+          )
+        end
+        resolved_rsa_dir = Pathname(rsa_dir(customer_id).realpath)
+        resolved = Pathname(key_dir).expand_path
+        resolved = Pathname(resolved.realpath) if resolved.exist?
+        unless resolved.parent == resolved_rsa_dir
+          raise Error.new(
+            code: ErrorCode::ERR_RSA_VERSION_MISSING,
+            message: "Key folder is not under rsa/ for #{customer_id}",
+          )
+        end
+        unless valid_rsa_key_dir?(resolved)
+          raise Error.new(
+            code: ErrorCode::ERR_RSA_VERSION_MISSING,
+            message: "Key folder missing public.pem or private.pem: #{resolved.basename}",
+          )
+        end
+        begin
+          FileUtils.remove_entry_secure(resolved)
+        rescue SystemCallError => exc
+          raise Error.new(
+            code: ErrorCode::ERR_VAULT_IO,
+            message: "Failed to delete key folder #{resolved.basename}: #{exc.message}",
+          )
+        end
+      end
+
+      def trial_unwrap_cek(customer_id, cek_wrapped)
+        Config.validate_customer_id!(customer_id)
+        unless cek_wrapped.bytesize == Config::RSA_2048_CIPHERTEXT_BYTES
+          raise Error.new(
+            code: ErrorCode::ERR_CENC_CEKA_WRAP,
+            message: "Wrapped CEK must be #{Config::RSA_2048_CIPHERTEXT_BYTES} bytes",
+          )
+        end
+
+        eligible = list_rsa_versions(customer_id).filter_map do |version|
+          meta = load_rsa_meta(customer_id, version)
+          next nil unless meta.rsa_bits == 2048
+          priv = get_private_key(customer_id, version)
+          next nil unless priv.n.num_bits == 2048
+          [version, priv]
+        end
+
+        if eligible.empty?
+          raise Error.new(
+            code: ErrorCode::ERR_CENC_CEKA_TRIAL_FAILED,
+            message: "No 2048-bit RSA keys available for trial unwrap: #{customer_id}",
+          )
+        end
+
+        first_success = nil
+        eligible.each do |version, priv|
+          begin
+            cek = RSAOAEP.unwrap_cek(cek_wrapped, priv)
+          rescue Error
+            next
+          end
+          return first_success if first_success
+          first_success = CekTrialUnwrapResult.new(cek: cek, rsa_key_version: version)
+        end
+
+        unless first_success
+          raise Error.new(
+            code: ErrorCode::ERR_CENC_CEKA_TRIAL_FAILED,
+            message: "CEK trial unwrap failed for all vault versions: #{customer_id}",
+          )
+        end
+        first_success
+      end
+
+      private
+
+      def valid_rsa_key_dir?(path)
+        path = Pathname(path)
+        path.directory? &&
+          self.class.public_pem_path_for_dir(path).file? &&
+          self.class.private_pem_path_for_dir(path).file?
+      end
+
+      def load_public_key_from(path)
+        key = OpenSSL::PKey::RSA.new(path.binread)
+        if key.private?
+          raise Error.new(code: ErrorCode::ERR_RSA_IMPORT_INVALID, message: 'PEM is not an RSA public key')
+        end
+        key
+      end
+
+      def load_private_key_from(path)
+        key = OpenSSL::PKey::RSA.new(path.binread)
+        unless key.private?
+          raise Error.new(code: ErrorCode::ERR_RSA_IMPORT_INVALID, message: 'PEM is not an RSA private key')
+        end
+        key
+      end
+    end
+  end
+end

data/lib/robocap/sdk/mp4_cenc.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+require 'pathname'
+require_relative 'config'
+require_relative 'errors'
+require_relative 'ffmpeg_cli'
+
+module Robocap
+  module SDK
+    CencMp4Metadata = Data.define(:customer_id, :cek_wrapped, :kid_hex)
+
+    module Mp4Cenc
+      CEKA_TAG                 = 'cenc_cek_wrapped_b64'
+      CUSTOMER_ID_TAG          = 'cenc_customer_id'
+      CUSTOMER_ID_FALLBACK_TAG = 'username'
+      KID_TAG                  = 'cenc_kid_hex'
+
+      CENC_WRAPPED_ALGO_TAG = 'cenc_wrapped_algo'
+
+      CENC_STRIP_TAGS_ON_DECRYPT = [
+        CEKA_TAG,
+        CENC_WRAPPED_ALGO_TAG,
+      ].freeze
+
+      module_function
+
+      def read_format_tags(mp4_path, ffprobe_executable: nil)
+        path = Pathname(mp4_path).expand_path
+        unless path.file?
+          raise Error.new(
+            code: ErrorCode::ERR_CENC_TAGS_MISSING,
+            message: "MP4 file not found: #{path}",
+          )
+        end
+        exe = FfmpegCli.resolve_ffprobe_executable(ffprobe_executable)
+        stdout, stderr, status = FfmpegCli.open3_capture3(
+          exe, '-v', 'error', '-show_format', '-print_format', 'json', path.to_s,
+        )
+        unless status.exitstatus.zero?
+          raise Error.new(
+            code: ErrorCode::ERR_CENC_FFPROBE_FAILED,
+            message: "ffprobe failed: #{stderr}",
+          )
+        end
+
+        payload = parse_ffprobe_json(stdout)
+        fmt = payload['format']
+        unless fmt.is_a?(Hash)
+          raise Error.new(
+            code: ErrorCode::ERR_CENC_TAGS_MISSING,
+            message: 'ffprobe output missing format section',
+          )
+        end
+        tags = fmt['tags']
+        unless tags.is_a?(Hash)
+          raise Error.new(
+            code: ErrorCode::ERR_CENC_TAGS_MISSING,
+            message: 'MP4 has no format metadata tags',
+          )
+        end
+        tags.transform_keys(&:to_s).transform_values(&:to_s)
+      end
+
+      def parse_cenc_metadata_from_tags(tags)
+        unless tags[CEKA_TAG] && !tags[CEKA_TAG].empty?
+          raise Error.new(
+            code: ErrorCode::ERR_CENC_TAGS_MISSING,
+            message: "Missing CENC tags: #{CEKA_TAG}",
+          )
+        end
+
+        customer_id = resolve_customer_id(tags)
+
+        begin
+          cek_wrapped = Base64.strict_decode64(tags[CEKA_TAG])
+        rescue ArgumentError
+          raise Error.new(
+            code: ErrorCode::ERR_CENC_TAGS_MISSING,
+            message: 'Invalid cenc_cek_wrapped_b64 Base64',
+          )
+        end
+
+        unless cek_wrapped.bytesize == Config::RSA_2048_CIPHERTEXT_BYTES
+          raise Error.new(
+            code: ErrorCode::ERR_CENC_CEKA_WRAP,
+            message: "Wrapped CEK must be #{Config::RSA_2048_CIPHERTEXT_BYTES} bytes",
+          )
+        end
+
+        kid = tags[KID_TAG]
+        kid = kid.strip.downcase if kid
+        kid = nil if kid && kid.empty?
+
+        CencMp4Metadata.new(customer_id: customer_id, cek_wrapped: cek_wrapped, kid_hex: kid)
+      end
+
+      def load_cenc_metadata(mp4_path, ffprobe_executable: nil)
+        parse_cenc_metadata_from_tags(
+          read_format_tags(mp4_path, ffprobe_executable: ffprobe_executable),
+        )
+      end
+
+      def has_cenc_tags(mp4_path, ffprobe_executable: nil)
+        tags = read_format_tags(mp4_path, ffprobe_executable: ffprobe_executable)
+        return false unless tags[CEKA_TAG] && !tags[CEKA_TAG].empty?
+        has_customer_id_source?(tags)
+      rescue Error
+        false
+      end
+
+      class << self
+        private
+
+        def parse_ffprobe_json(raw)
+          JSON.parse(raw)
+        rescue JSON::ParserError
+          raise Error.new(
+            code: ErrorCode::ERR_CENC_FFPROBE_FAILED,
+            message: 'ffprobe returned invalid JSON',
+          )
+        end
+
+        def resolve_customer_id(tags)
+          raw = tags[CUSTOMER_ID_TAG] || tags[CUSTOMER_ID_FALLBACK_TAG]
+          if raw.nil? || raw.strip.empty?
+            raise Error.new(
+              code: ErrorCode::ERR_CENC_TAGS_MISSING,
+              message: "Missing CENC customer id: #{CUSTOMER_ID_TAG} or #{CUSTOMER_ID_FALLBACK_TAG} tag required",
+            )
+          end
+          customer = raw.strip
+          begin
+            Config.validate_customer_id!(customer)
+          rescue ArgumentError
+            raise Error.new(
+              code: ErrorCode::ERR_CENC_CUSTOMER_ID_INVALID,
+              message: "Invalid customer id: #{customer.inspect}",
+            )
+          end
+          customer
+        end
+
+        def has_customer_id_source?(tags)
+          [CUSTOMER_ID_TAG, CUSTOMER_ID_FALLBACK_TAG].any? do |k|
+            v = tags[k]
+            v && !v.strip.empty?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/robocap/sdk/ownership.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'openssl'
+require_relative 'config'
+require_relative 'errors'
+require_relative 'key_vault'
+
+module Robocap
+  module SDK
+    VerifiedKeyVersion = Data.define(:customer_id, :matched_rsa_key_version, :public_fingerprint)
+
+    module Ownership
+      module_function
+
+      def spki_fingerprint(public_key)
+        der = public_key.public_to_der
+        Digest::SHA256.hexdigest(der)
+      end
+
+      def verify(customer_id:, user_private_pem:, key_vault: nil, sdk_root: nil)
+        vault = key_vault || KeyVault.new(sdk_root || Config.default_sdk_root)
+
+        unless vault.exists_customer?(customer_id)
+          raise Error.new(
+            code: ErrorCode::ERR_CUSTOMER_NOT_FOUND,
+            message: "Customer #{customer_id} not found in key vault",
+          )
+        end
+
+        priv = begin
+          OpenSSL::PKey::RSA.new(user_private_pem)
+        rescue OpenSSL::PKey::RSAError, OpenSSL::PKey::PKeyError => exc
+          raise Error.new(
+            code: ErrorCode::ERR_KEY_OWNERSHIP_FAILED,
+            message: 'Failed to parse user private key',
+            detail: { reason: exc.message },
+          )
+        end
+
+        unless priv.private?
+          raise Error.new(
+            code: ErrorCode::ERR_KEY_OWNERSHIP_FAILED,
+            message: 'User key is not an RSA private key',
+          )
+        end
+
+        user_fp = spki_fingerprint(priv.public_key)
+
+        vault.list_rsa_versions(customer_id).each do |version|
+          archived = vault.get_public_key(customer_id, version)
+          archived_fp = spki_fingerprint(archived)
+          if archived_fp == user_fp
+            return VerifiedKeyVersion.new(
+              customer_id: customer_id,
+              matched_rsa_key_version: version,
+              public_fingerprint: user_fp,
+            )
+          end
+        end
+
+        raise Error.new(
+          code: ErrorCode::ERR_KEY_OWNERSHIP_FAILED,
+          message: "User private key does not match any archived key for #{customer_id}",
+        )
+      end
+    end
+  end
+end

data/lib/robocap/sdk/rsa_delete.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative 'config'
+require_relative 'key_vault'
+
+module Robocap
+  module SDK
+    DeleteRsaResult = Data.define(:customer_id, :folder_name, :key_dir)
+
+    module RsaDelete
+      module_function
+
+      def call(customer_id:, rsa_key_version:, sdk_root: nil)
+        root = Pathname(sdk_root || Config.default_sdk_root)
+        vault = KeyVault.new(root)
+        key_dir = vault.rsa_version_dir(customer_id, rsa_key_version)
+        vault.delete_rsa_version(customer_id, rsa_key_version)
+        DeleteRsaResult.new(
+          customer_id: customer_id,
+          folder_name: key_dir.basename.to_s,
+          key_dir: key_dir,
+        )
+      end
+
+      def call_with_dir(customer_id:, key_dir:, sdk_root: nil)
+        root = Pathname(sdk_root || Config.default_sdk_root)
+        vault = KeyVault.new(root)
+        resolved = Pathname(key_dir).expand_path
+        resolved = Pathname(resolved.realpath) if resolved.exist?
+        folder_name = resolved.basename.to_s
+        vault.delete_rsa_key_dir(customer_id, resolved)
+        DeleteRsaResult.new(
+          customer_id: customer_id,
+          folder_name: folder_name,
+          key_dir: resolved,
+        )
+      end
+    end
+  end
+end

data/lib/robocap/sdk/rsa_import.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative 'config'
+require_relative 'key_vault'
+require_relative 'rsa_key_meta'
+
+module Robocap
+  module SDK
+    ImportRsaResult = Data.define(:customer_id, :rsa_key_version, :vault_rsa_dir)
+
+    module RsaImport
+      module_function
+
+      def call(customer_id:, public_pem:, private_pem:, meta:, sdk_root: nil)
+        root = Pathname(sdk_root || Config.default_sdk_root)
+        vault = KeyVault.new(root)
+        version = vault.import_rsa_version(
+          customer_id: customer_id,
+          public_pem: public_pem,
+          private_pem: private_pem,
+          meta: meta,
+        )
+        ImportRsaResult.new(
+          customer_id: customer_id,
+          rsa_key_version: version,
+          vault_rsa_dir: vault.rsa_version_dir(customer_id, version),
+        )
+      end
+    end
+  end
+end

data/lib/robocap/sdk/rsa_key_meta.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+require_relative 'config'
+
+module Robocap
+  module SDK
+    class RsaKeyMeta < Data.define(:rsa_key_version, :effective_at, :device_id, :rsa_bits)
+      def initialize(rsa_key_version:, effective_at:, device_id:, rsa_bits: Config::RSA_BITS)
+        unless rsa_key_version.is_a?(Integer) && rsa_key_version >= 1
+          raise ArgumentError, "rsa_key_version must be an integer >= 1 (got #{rsa_key_version.inspect})"
+        end
+        unless effective_at.is_a?(Time)
+          raise ArgumentError, "effective_at must be a Time (got #{effective_at.class})"
+        end
+        unless device_id.is_a?(String)
+          raise ArgumentError, "device_id must be a String (got #{device_id.class})"
+        end
+        unless rsa_bits.is_a?(Integer)
+          raise ArgumentError, "rsa_bits must be an Integer (got #{rsa_bits.class})"
+        end
+        super
+      end
+
+      def to_json(*_args)
+        JSON.generate(
+          rsa_key_version: rsa_key_version,
+          effective_at: effective_at.getutc.iso8601,
+          device_id: device_id,
+          rsa_bits: rsa_bits,
+        )
+      end
+
+      def to_pretty_json
+        JSON.pretty_generate(
+          'rsa_key_version' => rsa_key_version,
+          'effective_at' => effective_at.getutc.iso8601,
+          'device_id' => device_id,
+          'rsa_bits' => rsa_bits,
+        )
+      end
+
+      def self.from_json(str)
+        h = JSON.parse(str)
+        new(
+          rsa_key_version: h.fetch('rsa_key_version'),
+          effective_at: Time.iso8601(h.fetch('effective_at')),
+          device_id: h.fetch('device_id'),
+          rsa_bits: h.fetch('rsa_bits', Config::RSA_BITS),
+        )
+      end
+    end
+  end
+end