robocap-decryption-sdk 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a5c60c2503cabf98d07480ea6cb28d0068b4ba3b292815c7474cabe6fb6614a6
+  data.tar.gz: c10616d9b302342d67a70e9e9882befd1bfcce88a7c64963e2429362778140ed
+SHA512:
+  metadata.gz: ea720dfee5ddf6b53acad53ab0e8b91ad0c32f0037712a78da9f7b0a58e6a0b4822d94265f94c42c7a62e6f31c0aa33ad50a6cb3e46be2e2b49ddc87c304deea
+  data.tar.gz: 9078269ccd590ed466d9912c7df09d42f84e647dd22c7f0edf701f3d753b9c27d29ff13a883aaca3acffc75c52d9868c69c1b7ec13c1a5cf3f8254e48da96f88

data/README.md

@@ -0,0 +1,39 @@
+# Robocap Decryption SDK — Ruby
+
+Offline import of RSA keys and decryption of CENC-encrypted MP4 files.
+
+This is the Ruby implementation. The shared format spec and test fixtures
+live one directory up at the monorepo root — see [`../README.md`](../README.md).
+
+## Requirements
+
+- Ruby 3.2+
+- OpenSSL 3.x (system or brewed) — required for RSA-OAEP-SHA256
+- `ffmpeg` and `ffprobe` on `PATH` (for `decrypt-cenc`)
+
+## Install (from git checkout)
+
+```bash
+cd ruby
+bundle install
+```
+
+## Tests
+
+```bash
+bundle exec rake test
+```
+
+## CLI
+
+```bash
+bundle exec exe/robocap-decryption-sdk import-rsa  --help
+bundle exec exe/robocap-decryption-sdk delete-rsa  --help
+bundle exec exe/robocap-decryption-sdk decrypt-cenc --help
+```
+
+## Verified against the Python SDK
+
+This Ruby gem reads and writes the same on-disk vault and CENC MP4 format
+as `python/`. To re-verify byte-compatibility, follow the manual checks
+in [`../spec/cross-sdk-verification.md`](../spec/cross-sdk-verification.md).

data/exe/robocap-decryption-sdk

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'robocap/sdk/cli'
+
+exit Robocap::SDK::CLI.run(ARGV.dup)

data/lib/robocap/sdk/cli.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'optparse'
+require 'pathname'
+require 'time'
+require_relative '../sdk'
+
+module Robocap
+  module SDK
+    module CLI
+      module_function
+
+      USAGE = <<~TXT
+        Usage: robocap-decryption-sdk <command> [options]
+
+        Commands:
+          import-rsa     Import an RSA key pair into the vault
+          delete-rsa     Delete one RSA key version from the vault
+          decrypt-cenc   Decrypt a CENC MP4 (RSA-OAEP CEK unwrap + ffmpeg)
+
+        Run `robocap-decryption-sdk <command> --help` for command-specific options.
+      TXT
+
+      def run(argv)
+        command = argv.shift
+        case command
+        when 'import-rsa'   then with_error_handling { cmd_import_rsa(argv) }
+        when 'delete-rsa'   then with_error_handling { cmd_delete_rsa(argv) }
+        when 'decrypt-cenc' then with_error_handling { cmd_decrypt_cenc(argv) }
+        when '--help', '-h', nil
+          warn(USAGE)
+          0
+        else
+          warn("Unknown command: #{command}\n\n#{USAGE}")
+          2
+        end
+      end
+
+      def with_error_handling
+        yield
+        0
+      rescue Error => exc
+        warn(JSON.generate(exc.to_h))
+        1
+      rescue OptionParser::ParseError => exc
+        warn(exc.message)
+        2
+      end
+
+      def emit_json(data)
+        puts JSON.generate(data)
+      end
+
+      def cmd_import_rsa(argv)
+        opts = {}
+        OptionParser.new do |o|
+          o.banner = 'Usage: robocap-decryption-sdk import-rsa [options]'
+          o.on('--customer-id CID')       { |v| opts[:customer_id] = v }
+          o.on('--public-key PATH')       { |v| opts[:public_key] = Pathname(v) }
+          o.on('--private-key PATH')      { |v| opts[:private_key] = Pathname(v) }
+          o.on('--rsa-key-version N', Integer) { |v| opts[:rsa_key_version] = v }
+          o.on('--rsa-bits N',     ['2048', '4096']) { |v| opts[:rsa_bits] = v.to_i }
+          o.on('--device-id ID')          { |v| opts[:device_id] = v }
+          o.on('--effective-at ISO8601')  { |v| opts[:effective_at] = v }
+          o.on('--sdk-root PATH')         { |v| opts[:sdk_root] = Pathname(v) }
+        end.parse!(argv)
+
+        require_opts!(opts, %i[customer_id public_key private_key rsa_key_version])
+        opts[:rsa_bits] ||= 2048
+        eff = opts[:effective_at] ? Time.iso8601(opts[:effective_at]) : Time.now.utc
+        meta = RsaKeyMeta.new(
+          rsa_key_version: opts[:rsa_key_version],
+          effective_at: eff,
+          device_id: opts[:device_id] || opts[:customer_id],
+          rsa_bits: opts[:rsa_bits],
+        )
+        result = Robocap::SDK.import_rsa_key_version(
+          customer_id: opts[:customer_id],
+          public_pem: opts[:public_key].binread,
+          private_pem: opts[:private_key].binread,
+          meta: meta,
+          sdk_root: opts[:sdk_root],
+        )
+        emit_json(
+          status: 'ok',
+          customer_id: result.customer_id,
+          rsa_key_version: result.rsa_key_version,
+          vault_rsa_dir: result.vault_rsa_dir.to_s,
+        )
+      end
+
+      def cmd_delete_rsa(argv)
+        opts = {}
+        OptionParser.new do |o|
+          o.banner = 'Usage: robocap-decryption-sdk delete-rsa [options]'
+          o.on('--customer-id CID') { |v| opts[:customer_id] = v }
+          o.on('--rsa-key-version N', Integer) { |v| opts[:rsa_key_version] = v }
+          o.on('--sdk-root PATH')   { |v| opts[:sdk_root] = Pathname(v) }
+        end.parse!(argv)
+
+        require_opts!(opts, %i[customer_id rsa_key_version])
+        result = Robocap::SDK.delete_rsa_key_version(
+          customer_id: opts[:customer_id],
+          rsa_key_version: opts[:rsa_key_version],
+          sdk_root: opts[:sdk_root],
+        )
+        emit_json(
+          status: 'ok',
+          customer_id: result.customer_id,
+          rsa_key_version: opts[:rsa_key_version],
+          folder_name: result.folder_name,
+        )
+      end
+
+      def cmd_decrypt_cenc(argv)
+        opts = {}
+        OptionParser.new do |o|
+          o.banner = 'Usage: robocap-decryption-sdk decrypt-cenc [options]'
+          o.on('--mp4-path PATH')     { |v| opts[:mp4_path] = Pathname(v) }
+          o.on('--private-key PATH')  { |v| opts[:private_key] = Pathname(v) }
+          o.on('--output-dir PATH')   { |v| opts[:output_dir] = Pathname(v) }
+          o.on('--sdk-root PATH')     { |v| opts[:sdk_root] = Pathname(v) }
+          o.on('--ffmpeg PATH')       { |v| opts[:ffmpeg_executable] = v }
+          o.on('--ffprobe PATH')      { |v| opts[:ffprobe_executable] = v }
+        end.parse!(argv)
+
+        require_opts!(opts, %i[mp4_path private_key output_dir])
+        opts[:output_dir].mkpath
+        result = Robocap::SDK.decrypt_cenc_mp4(
+          mp4_path: opts[:mp4_path],
+          user_private_pem: opts[:private_key].binread,
+          output_dir: opts[:output_dir],
+          sdk_root: opts[:sdk_root],
+          ffmpeg_executable: opts[:ffmpeg_executable],
+          ffprobe_executable: opts[:ffprobe_executable],
+        )
+        emit_json(
+          status: 'ok',
+          output_path: result.output_path.to_s,
+          customer_id: result.customer_id,
+          rsa_key_version: result.rsa_key_version,
+          kid_hex: result.kid_hex,
+        )
+      end
+
+      def require_opts!(opts, keys)
+        missing = keys.reject { |k| opts.key?(k) }
+        return if missing.empty?
+        raise OptionParser::ParseError, "missing required option(s): #{missing.map { |k| "--#{k.to_s.tr('_', '-')}" }.join(', ')}"
+      end
+    end
+  end
+end

data/lib/robocap/sdk/config.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+module Robocap
+  module SDK
+    module Config
+      VAULT_KEYS_DIR  = 'vault/keys'
+      VAULT_FILES_DIR = 'vault/files'
+
+      RSA_BITS                  = 4096
+      RSA_BITS_ALLOWED          = [2048, 4096].freeze
+      RSA_PUBLIC_EXPONENT       = 65_537
+      RSA_PADDING_SCHEME        = 'OAEP_SHA256'
+      RSA_OAEP_HASH             = 'sha256'
+      RSA_OAEP_MGF_HASH         = 'sha256'
+      RSA_OAEP_LABEL            = nil
+      RSA_CIPHERTEXT_BYTES      = 512
+      RSA_2048_CIPHERTEXT_BYTES = 256
+
+      CEK_BYTES       = 16
+      AES_KEY_BYTES   = 32
+      AES_NONCE_BYTES = 12
+      AES_TAG_BYTES   = 16
+
+      K2_MAGIC               = "RCK2".b.freeze
+      K2_FORMAT_VERSION      = 1
+      K2_HEADER_BYTES        = 9
+      K2_BLOB_MIN_BYTES      = K2_HEADER_BYTES + RSA_CIPHERTEXT_BYTES
+      META_FORMAT_VERSION    = 1
+
+      DEFAULT_AES_BACKEND     = 'cryptography'
+      AES_BACKEND_OPENSSL     = 'openssl_cli'
+      OPENSSL_ENV_VAR         = 'ROBOCAP_OPENSSL'
+      FFMPEG_ENV_VAR          = 'ROBOCAP_FFMPEG'
+      FFPROBE_ENV_VAR         = 'ROBOCAP_FFPROBE'
+
+      MASTER_KEY_FILENAME  = '.master_key'
+      DEVICE_AES_FILENAME  = 'device_aes.enc.pem'
+
+      CUSTOMER_ID_PATTERN = /\A[A-Za-z0-9_\-]+\z/
+
+      module_function
+
+      def default_sdk_root
+        path = ENV['ROBOCAP_SDK_ROOT']
+        path && !path.empty? ? Pathname(path) : Pathname(Dir.home).join('.robocap-sdk')
+      end
+
+      def validate_customer_id!(customer_id)
+        unless customer_id.is_a?(String) && customer_id.match?(CUSTOMER_ID_PATTERN)
+          raise ArgumentError,
+                "Invalid customer_id: #{customer_id.inspect} " \
+                '(allowed: alphanumeric, underscore, hyphen)'
+        end
+      end
+
+      def keys_vault_root(sdk_root)
+        Pathname(sdk_root).join(VAULT_KEYS_DIR)
+      end
+
+      def files_vault_root(sdk_root)
+        Pathname(sdk_root).join(VAULT_FILES_DIR)
+      end
+    end
+  end
+end

data/lib/robocap/sdk/decrypt_cenc.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative 'config'
+require_relative 'errors'
+require_relative 'key_vault'
+require_relative 'mp4_cenc'
+require_relative 'ownership'
+require_relative 'ffmpeg_cli'
+require_relative 'vault_layout'
+
+module Robocap
+  module SDK
+    DecryptCencResult = Data.define(:output_path, :customer_id, :rsa_key_version, :kid_hex)
+
+    module DecryptCenc
+      module_function
+
+      def call(mp4_path:, user_private_pem:, output_dir:,
+               sdk_root: nil, ffprobe_executable: nil, ffmpeg_executable: nil)
+        mp4_path   = Pathname(mp4_path)
+        output_dir = Pathname(output_dir)
+
+        meta = Mp4Cenc.load_cenc_metadata(mp4_path, ffprobe_executable: ffprobe_executable)
+
+        root = Pathname(sdk_root || Config.default_sdk_root)
+        vault = KeyVault.new(root)
+
+        unless vault.exists_customer?(meta.customer_id)
+          raise Error.new(
+            code: ErrorCode::ERR_CUSTOMER_NOT_FOUND,
+            message: "Customer not found in vault: #{meta.customer_id}",
+          )
+        end
+
+        Ownership.verify(
+          customer_id: meta.customer_id,
+          user_private_pem: user_private_pem,
+          key_vault: vault,
+        )
+
+        trial = vault.trial_unwrap_cek(meta.customer_id, meta.cek_wrapped)
+        cek_hex = trial.cek.unpack1('H*')
+
+        VaultLayout.ensure_private_dir(output_dir)
+        out_path = output_dir.join(mp4_path.basename)
+        FfmpegCli.decrypt_cenc_copy(
+          input_mp4: mp4_path,
+          output_mp4: out_path,
+          cek_hex: cek_hex,
+          kid_hex: meta.kid_hex,
+          ffmpeg_executable: ffmpeg_executable,
+        )
+
+        DecryptCencResult.new(
+          output_path: out_path,
+          customer_id: meta.customer_id,
+          rsa_key_version: trial.rsa_key_version,
+          kid_hex: meta.kid_hex,
+        )
+      end
+    end
+  end
+end

data/lib/robocap/sdk/errors.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Robocap
+  module SDK
+    module ErrorCode
+      ERR_CUSTOMER_NOT_FOUND        = 1001
+      ERR_CUSTOMER_ALREADY_EXISTS   = 1002
+      ERR_KEY_OWNERSHIP_FAILED      = 2001
+      ERR_CUSTOMER_MISMATCH         = 2002
+      ERR_RSA_VERSION_MISSING       = 3001
+      ERR_K2_META_VERSION_MISMATCH  = 3002
+      ERR_K2_DECODE                 = 3003
+      ERR_K2_PLAINTEXT_LENGTH       = 3004
+      ERR_SIDECAR_INCOMPLETE        = 4001
+      ERR_META_VALIDATION           = 4002
+      ERR_DECRYPT_AUTH_TAG          = 5001
+      ERR_SHA256_MISMATCH           = 5002
+      ERR_VAULT_IO                  = 6001
+      ERR_MASTER_KEY                = 6002
+      ERR_OPENSSL_CLI_UNAVAILABLE   = 6003
+      ERR_INVALID_RSA_BITS          = 6004
+      ERR_OPENSSL_CLI_FAILED        = 6005
+      ERR_RSA_IMPORT_INVALID        = 6006
+      ERR_RSA_NOT_IMPORTED          = 6007
+      ERR_DEVICE_AES_EXISTS         = 6008
+      ERR_RSA_V1_REQUIRED           = 6009
+      ERR_CENC_TAGS_MISSING         = 7001
+      ERR_CENC_CEKA_WRAP            = 7004
+      ERR_CENC_CEKA_LENGTH          = 7005
+      ERR_FFMPEG_NOT_FOUND          = 7006
+      ERR_FFPROBE_NOT_FOUND         = 7007
+      ERR_CENC_DECRYPT_FAILED       = 7008
+      ERR_CENC_FFPROBE_FAILED       = 7009
+      ERR_CENC_CUSTOMER_ID_INVALID  = 7010
+      ERR_CENC_CEKA_TRIAL_FAILED    = 7011
+
+      NAMES = constants.each_with_object({}) do |c, h|
+        v = const_get(c)
+        h[v] = c.to_s if v.is_a?(Integer)
+      end.freeze
+
+      module_function
+
+      def name_for(code)
+        NAMES.fetch(code) { "ERR_UNKNOWN_#{code}" }
+      end
+    end
+
+    class Error < StandardError
+      attr_reader :code, :detail
+
+      def initialize(code:, message:, detail: nil)
+        @code = code
+        @detail = detail
+        @plain_message = message
+        super("[#{ErrorCode.name_for(code)}] #{message}")
+      end
+
+      def to_h
+        {
+          code: @code,
+          error: ErrorCode.name_for(@code),
+          message: @plain_message,
+          detail: @detail,
+        }
+      end
+    end
+  end
+end

data/lib/robocap/sdk/ffmpeg_cli.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'fileutils'
+require 'pathname'
+require_relative 'config'
+require_relative 'errors'
+
+module Robocap
+  module SDK
+    module FfmpegCli
+      module_function
+
+      def open3_capture3(*args)
+        Open3.capture3(*args)
+      end
+
+      def resolve_ffprobe_executable(explicit = nil)
+        resolve_executable(
+          explicit: explicit,
+          tool: 'ffprobe',
+          sibling_for: ENV['ROBOCAP_FFMPEG'],
+          missing_code: ErrorCode::ERR_FFPROBE_NOT_FOUND,
+          env_key: Config::FFPROBE_ENV_VAR,
+        )
+      end
+
+      def resolve_ffmpeg_executable(explicit = nil)
+        resolve_executable(
+          explicit: explicit,
+          tool: 'ffmpeg',
+          sibling_for: nil,
+          missing_code: ErrorCode::ERR_FFMPEG_NOT_FOUND,
+          env_key: Config::FFMPEG_ENV_VAR,
+        )
+      end
+
+      def decrypt_cenc_copy(input_mp4:, output_mp4:, cek_hex:, kid_hex: nil, ffmpeg_executable: nil)
+        exe = resolve_ffmpeg_executable(ffmpeg_executable)
+        FileUtils.mkdir_p(Pathname(output_mp4).parent)
+        cmd = [exe, '-y', '-decryption_key', cek_hex]
+        cmd.push('-decryption_kid', kid_hex) if kid_hex && !kid_hex.empty?
+        cmd.push(
+          '-i', input_mp4.to_s,
+          '-map', '0',
+          '-map_metadata', '0',
+          '-c', 'copy',
+          '-movflags', '+use_metadata_tags',
+        )
+        Mp4Cenc::CENC_STRIP_TAGS_ON_DECRYPT.each do |tag|
+          cmd.push('-metadata', "#{tag}=")
+        end
+        cmd.push(output_mp4.to_s)
+
+        begin
+          _stdout, stderr, status = open3_capture3(*cmd)
+        rescue SystemCallError => exc
+          raise Error.new(
+            code: ErrorCode::ERR_CENC_DECRYPT_FAILED,
+            message: 'ffmpeg CENC decrypt subprocess failed',
+            detail: { reason: exc.message },
+          )
+        end
+
+        return if status.exitstatus.zero?
+        raise Error.new(
+          code: ErrorCode::ERR_CENC_DECRYPT_FAILED,
+          message: "ffmpeg CENC decrypt failed: #{stderr}",
+        )
+      end
+
+      class << self
+        private
+
+        def resolve_executable(explicit:, tool:, sibling_for:, missing_code:, env_key:)
+          if explicit && !explicit.empty?
+            path = Pathname(explicit)
+            return path.to_s if path.file?
+            return explicit unless explicit.include?('/') || explicit.include?('\\')
+            raise Error.new(code: missing_code, message: "#{tool} executable not found: #{explicit}")
+          end
+          env_path = ENV[env_key]
+          return env_path if env_path && Pathname(env_path).file?
+          if sibling_for
+            sib = Pathname(sibling_for)
+            if sib.file?
+              sibling = sib.dirname.join(tool + (sib.extname.downcase == '.exe' ? '.exe' : ''))
+              return sibling.to_s if sibling.file?
+            end
+          end
+          found = which(tool)
+          return found if found
+          raise Error.new(code: missing_code, message: "#{tool} executable not found in PATH")
+        end
+
+        def which(name)
+          exts = ENV['PATHEXT'] ? ENV['PATHEXT'].split(File::PATH_SEPARATOR) : ['']
+          ENV.fetch('PATH', '').split(File::PATH_SEPARATOR).each do |dir|
+            exts.each do |ext|
+              candidate = File.join(dir, name + ext)
+              return candidate if File.executable?(candidate) && !File.directory?(candidate)
+            end
+          end
+          nil
+        end
+      end
+    end
+  end
+end