robocap-decryption-sdk 1.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5c60c2503cabf98d07480ea6cb28d0068b4ba3b292815c7474cabe6fb6614a6
-  data.tar.gz: c10616d9b302342d67a70e9e9882befd1bfcce88a7c64963e2429362778140ed
+  metadata.gz: 79e885213cb75dc85172a8a8c8eb17baa9b3684ee6dff10e331d3e6262c2aefe
+  data.tar.gz: 84077253d5bf58dcf7c658512efc7274bf13c3cf6e30eaa87549ef0f73fa99e0
 SHA512:
-  metadata.gz: ea720dfee5ddf6b53acad53ab0e8b91ad0c32f0037712a78da9f7b0a58e6a0b4822d94265f94c42c7a62e6f31c0aa33ad50a6cb3e46be2e2b49ddc87c304deea
-  data.tar.gz: 9078269ccd590ed466d9912c7df09d42f84e647dd22c7f0edf701f3d753b9c27d29ff13a883aaca3acffc75c52d9868c69c1b7ec13c1a5cf3f8254e48da96f88
+  metadata.gz: 1ada52a6ef96f5a2a0726e97365b48c6f0452e84f09d5916269aacc94fc8e3fedfdc8da924396baff5fb45aafe9ed5aad6a364684b31357425491895bd02d7eb
+  data.tar.gz: 449d464f2324500cd1409ed6b3d42dcaa639b2d482614db00432671e2a8afc33393711534db9ad9c7cc8f56222dee130a14fae582e8da96ad1836d150367b371

data/README.md

@@ -32,6 +32,44 @@ bundle exec exe/robocap-decryption-sdk delete-rsa  --help
 bundle exec exe/robocap-decryption-sdk decrypt-cenc --help
 ```
 
+## Ruby API
+
+```ruby
+require 'robocap/sdk'
+
+RobocapCenc::SDK.decrypt_cenc_mp4(...)
+```
+
+## Changelog
+
+### 2.1.0
+
+Brings the Ruby SDK to parity with the Python SDK's device/host vault
+resolution. See [`../spec/cenc-tags.md`](../spec/cenc-tags.md) for the full
+contract.
+
+BREAKING: the `username` MP4 tag is no longer a customer-id source. The
+fallback tag is now `deviceid`. A capture whose only customer-id source is
+`username` now fails `ERR_CENC_TAGS_MISSING` — re-tag it with `deviceid`.
+
+- Product line is detected from the MP4 filename stem (`robowrist_` /
+  `robocap_` / otherwise legacy) via `Mp4Cenc.detect_product_line`.
+- `robowrist` captures resolve their vault customer id from the `host` tag
+  instead of the device id. Import robowrist keys under the **host**.
+- `CencMp4Metadata` gained `product_line`, `tag_deviceid`, and `tag_host`.
+- New `ERR_DEVICE_BINDING_MISMATCH` (7012) plus
+  `Mp4Cenc.verify_session_device_id` / `verify_session_device_id_from_metadata`.
+- `DecryptCenc.call` accepts `metadata:` (skip re-probing an already-parsed
+  file) and `session_device_id:` (bind decryption to one device).
+- `parse_cenc_metadata_from_tags` now takes optional `mp4_path:` /
+  `product_line:` keywords. Callers passing a **literal** bare hash must brace
+  it — `parse_cenc_metadata_from_tags({ 'k' => 'v' })` — since Ruby would
+  otherwise read it as keyword arguments. Passing a hash variable is unaffected.
+
+### 2.0.0
+
+BREAKING: Ruby namespace renamed `Robocap::SDK` -> `RobocapCenc::SDK` to avoid colliding with host apps that define a top-level `Robocap` constant. Gem name, require path, and CLI executable are unchanged. Ruby API consumers must update `Robocap::SDK::*` references to `RobocapCenc::SDK::*`.
+
 ## Verified against the Python SDK
 
 This Ruby gem reads and writes the same on-disk vault and CENC MP4 format

data/exe/robocap-decryption-sdk

@@ -3,4 +3,4 @@
 
 require 'robocap/sdk/cli'
 
-exit Robocap::SDK::CLI.run(ARGV.dup)
+exit RobocapCenc::SDK::CLI.run(ARGV.dup)

data/lib/robocap/sdk/cli.rb

@@ -6,7 +6,7 @@ require 'pathname'
 require 'time'
 require_relative '../sdk'
 
-module Robocap
+module RobocapCenc
   module SDK
     module CLI
       module_function
@@ -75,7 +75,7 @@ module Robocap
           device_id: opts[:device_id] || opts[:customer_id],
           rsa_bits: opts[:rsa_bits],
         )
-        result = Robocap::SDK.import_rsa_key_version(
+        result = RobocapCenc::SDK.import_rsa_key_version(
           customer_id: opts[:customer_id],
           public_pem: opts[:public_key].binread,
           private_pem: opts[:private_key].binread,
@@ -100,7 +100,7 @@ module Robocap
         end.parse!(argv)
 
         require_opts!(opts, %i[customer_id rsa_key_version])
-        result = Robocap::SDK.delete_rsa_key_version(
+        result = RobocapCenc::SDK.delete_rsa_key_version(
           customer_id: opts[:customer_id],
           rsa_key_version: opts[:rsa_key_version],
           sdk_root: opts[:sdk_root],
@@ -127,7 +127,7 @@ module Robocap
 
         require_opts!(opts, %i[mp4_path private_key output_dir])
         opts[:output_dir].mkpath
-        result = Robocap::SDK.decrypt_cenc_mp4(
+        result = RobocapCenc::SDK.decrypt_cenc_mp4(
           mp4_path: opts[:mp4_path],
           user_private_pem: opts[:private_key].binread,
           output_dir: opts[:output_dir],

data/lib/robocap/sdk/config.rb

@@ -2,7 +2,7 @@
 
 require 'pathname'
 
-module Robocap
+module RobocapCenc
   module SDK
     module Config
       VAULT_KEYS_DIR  = 'vault/keys'

data/lib/robocap/sdk/decrypt_cenc.rb

@@ -9,19 +9,25 @@ require_relative 'ownership'
 require_relative 'ffmpeg_cli'
 require_relative 'vault_layout'
 
-module Robocap
+module RobocapCenc
   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)
+      def call(mp4_path:, user_private_pem:, output_dir:, metadata: nil,
+               sdk_root: nil, session_device_id: 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)
+        meta = metadata ||
+               Mp4Cenc.load_cenc_metadata(mp4_path, ffprobe_executable: ffprobe_executable)
+
+        unless session_device_id.nil?
+          Mp4Cenc.verify_session_device_id_from_metadata(session_device_id, meta)
+        end
 
         root = Pathname(sdk_root || Config.default_sdk_root)
         vault = KeyVault.new(root)

data/lib/robocap/sdk/errors.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Robocap
+module RobocapCenc
   module SDK
     module ErrorCode
       ERR_CUSTOMER_NOT_FOUND        = 1001
@@ -33,6 +33,7 @@ module Robocap
       ERR_CENC_FFPROBE_FAILED       = 7009
       ERR_CENC_CUSTOMER_ID_INVALID  = 7010
       ERR_CENC_CEKA_TRIAL_FAILED    = 7011
+      ERR_DEVICE_BINDING_MISMATCH   = 7012
 
       NAMES = constants.each_with_object({}) do |c, h|
         v = const_get(c)

data/lib/robocap/sdk/ffmpeg_cli.rb

@@ -6,7 +6,7 @@ require 'pathname'
 require_relative 'config'
 require_relative 'errors'
 
-module Robocap
+module RobocapCenc
   module SDK
     module FfmpegCli
       module_function

data/lib/robocap/sdk/key_vault.rb

@@ -9,7 +9,7 @@ require_relative 'rsa_key_meta'
 require_relative 'rsa_oaep'
 require_relative 'vault_layout'
 
-module Robocap
+module RobocapCenc
   module SDK
     CekTrialUnwrapResult = Data.define(:cek, :rsa_key_version)
 

data/lib/robocap/sdk/mp4_cenc.rb

@@ -7,14 +7,32 @@ require_relative 'config'
 require_relative 'errors'
 require_relative 'ffmpeg_cli'
 
-module Robocap
+module RobocapCenc
   module SDK
-    CencMp4Metadata = Data.define(:customer_id, :cek_wrapped, :kid_hex)
+    PRODUCT_LINE_ROBOCAP   = 'robocap'
+    PRODUCT_LINE_ROBOWRIST = 'robowrist'
+    PRODUCT_LINE_LEGACY    = 'legacy'
+
+    PRODUCT_LINES = [
+      PRODUCT_LINE_ROBOCAP,
+      PRODUCT_LINE_ROBOWRIST,
+      PRODUCT_LINE_LEGACY,
+    ].freeze
+
+    CencMp4Metadata = Data.define(
+      :customer_id, :cek_wrapped, :kid_hex, :product_line, :tag_deviceid, :tag_host,
+    ) do
+      def initialize(customer_id:, cek_wrapped:, kid_hex: nil,
+                     product_line: PRODUCT_LINE_LEGACY, tag_deviceid: nil, tag_host: nil)
+        super
+      end
+    end
 
     module Mp4Cenc
       CEKA_TAG                 = 'cenc_cek_wrapped_b64'
       CUSTOMER_ID_TAG          = 'cenc_customer_id'
-      CUSTOMER_ID_FALLBACK_TAG = 'username'
+      CUSTOMER_ID_FALLBACK_TAG = 'deviceid'
+      HOST_TAG                 = 'host'
       KID_TAG                  = 'cenc_kid_hex'
 
       CENC_WRAPPED_ALGO_TAG = 'cenc_wrapped_algo'
@@ -63,7 +81,16 @@ module Robocap
         tags.transform_keys(&:to_s).transform_values(&:to_s)
       end
 
-      def parse_cenc_metadata_from_tags(tags)
+      # Product line is derived from the filename prefix, which decides whether
+      # the vault is keyed by the +deviceid+ or the +host+ tag.
+      def detect_product_line(mp4_path)
+        stem = Pathname(mp4_path).basename('.*').to_s.downcase
+        return PRODUCT_LINE_ROBOWRIST if stem.start_with?('robowrist_')
+        return PRODUCT_LINE_ROBOCAP if stem.start_with?('robocap_')
+        PRODUCT_LINE_LEGACY
+      end
+
+      def parse_cenc_metadata_from_tags(tags, mp4_path: nil, product_line: nil)
         unless tags[CEKA_TAG] && !tags[CEKA_TAG].empty?
           raise Error.new(
             code: ErrorCode::ERR_CENC_TAGS_MISSING,
@@ -71,7 +98,10 @@ module Robocap
           )
         end
 
-        customer_id = resolve_customer_id(tags)
+        line = product_line
+        line ||= mp4_path ? detect_product_line(mp4_path) : PRODUCT_LINE_LEGACY
+
+        customer_id = resolve_vault_customer_id(tags, line)
 
         begin
           cek_wrapped = Base64.strict_decode64(tags[CEKA_TAG])
@@ -93,23 +123,62 @@ module Robocap
         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)
+        CencMp4Metadata.new(
+          customer_id: customer_id,
+          cek_wrapped: cek_wrapped,
+          kid_hex: kid,
+          product_line: line,
+          tag_deviceid: tag_value(tags, CUSTOMER_ID_FALLBACK_TAG) || tag_value(tags, CUSTOMER_ID_TAG),
+          tag_host: tag_value(tags, HOST_TAG),
+        )
       end
 
       def load_cenc_metadata(mp4_path, ffprobe_executable: nil)
+        path = Pathname(mp4_path).expand_path
+        tags = read_format_tags(path, ffprobe_executable: ffprobe_executable)
         parse_cenc_metadata_from_tags(
-          read_format_tags(mp4_path, ffprobe_executable: ffprobe_executable),
+          tags, mp4_path: path, product_line: detect_product_line(path),
         )
       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)
+        path = Pathname(mp4_path).expand_path
+        tags = read_format_tags(path, ffprobe_executable: ffprobe_executable)
+        has_required_tags_for_product?(tags, detect_product_line(path))
       rescue Error
         false
       end
 
+      # Binds a caller-supplied device id to the tags embedded in the MP4 so a
+      # capture cannot be decrypted under a different device's session.
+      def verify_session_device_id(session_device_id, tags, product_line)
+        normalized = normalize_session_device_id(session_device_id)
+
+        if product_line == PRODUCT_LINE_ROBOWRIST
+          expected = tag_value(tags, HOST_TAG)
+          field = HOST_TAG
+        else
+          expected = tag_value(tags, CUSTOMER_ID_TAG) || tag_value(tags, CUSTOMER_ID_FALLBACK_TAG)
+          field = CUSTOMER_ID_TAG
+        end
+
+        assert_session_device_id_matches(expected, normalized, field)
+      end
+
+      def verify_session_device_id_from_metadata(session_device_id, meta)
+        normalized = normalize_session_device_id(session_device_id)
+
+        if meta.product_line == PRODUCT_LINE_ROBOWRIST
+          expected = meta.tag_host
+          field = HOST_TAG
+        else
+          expected = meta.tag_deviceid
+          field = CUSTOMER_ID_FALLBACK_TAG
+        end
+
+        assert_session_device_id_matches(expected, normalized, field)
+      end
+
       class << self
         private
 
@@ -122,7 +191,24 @@ module Robocap
           )
         end
 
-        def resolve_customer_id(tags)
+        def tag_value(tags, key)
+          raw = tags[key]
+          return nil if raw.nil?
+          stripped = raw.strip
+          stripped.empty? ? nil : stripped
+        end
+
+        def validate_customer_id_string(customer_id)
+          Config.validate_customer_id!(customer_id)
+          customer_id
+        rescue ArgumentError
+          raise Error.new(
+            code: ErrorCode::ERR_CENC_CUSTOMER_ID_INVALID,
+            message: "Invalid customer id: #{customer_id.inspect}",
+          )
+        end
+
+        def resolve_deviceid_from_tags(tags)
           raw = tags[CUSTOMER_ID_TAG] || tags[CUSTOMER_ID_FALLBACK_TAG]
           if raw.nil? || raw.strip.empty?
             raise Error.new(
@@ -130,23 +216,60 @@ module Robocap
               message: "Missing CENC customer id: #{CUSTOMER_ID_TAG} or #{CUSTOMER_ID_FALLBACK_TAG} tag required",
             )
           end
-          customer = raw.strip
+          validate_customer_id_string(raw.strip)
+        end
+
+        def resolve_vault_customer_id(tags, product_line)
+          if product_line == PRODUCT_LINE_ROBOWRIST
+            host = tag_value(tags, HOST_TAG)
+            if host.nil?
+              raise Error.new(
+                code: ErrorCode::ERR_CENC_TAGS_MISSING,
+                message: "Missing CENC host tag for robowrist: #{HOST_TAG} required",
+              )
+            end
+            return validate_customer_id_string(host)
+          end
+          resolve_deviceid_from_tags(tags)
+        end
+
+        def has_customer_id_source?(tags)
+          [CUSTOMER_ID_TAG, CUSTOMER_ID_FALLBACK_TAG].any? { |k| !tag_value(tags, k).nil? }
+        end
+
+        def has_required_tags_for_product?(tags, product_line)
+          return false unless tags[CEKA_TAG] && !tags[CEKA_TAG].empty?
+          if product_line == PRODUCT_LINE_ROBOWRIST
+            return !tag_value(tags, HOST_TAG).nil? && has_customer_id_source?(tags)
+          end
+          has_customer_id_source?(tags)
+        end
+
+        def normalize_session_device_id(session_device_id)
+          normalized = session_device_id.to_s.strip
+          if normalized.empty?
+            raise Error.new(
+              code: ErrorCode::ERR_DEVICE_BINDING_MISMATCH,
+              message: 'Session device id is empty',
+            )
+          end
           begin
-            Config.validate_customer_id!(customer)
+            Config.validate_customer_id!(normalized)
           rescue ArgumentError
             raise Error.new(
-              code: ErrorCode::ERR_CENC_CUSTOMER_ID_INVALID,
-              message: "Invalid customer id: #{customer.inspect}",
+              code: ErrorCode::ERR_DEVICE_BINDING_MISMATCH,
+              message: "Invalid session device id: #{normalized.inspect}",
             )
           end
-          customer
+          normalized
         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
+        def assert_session_device_id_matches(expected, normalized, field)
+          return if !expected.nil? && expected == normalized
+          raise Error.new(
+            code: ErrorCode::ERR_DEVICE_BINDING_MISMATCH,
+            message: "Session device id does not match MP4 #{field} tag",
+          )
         end
       end
     end

data/lib/robocap/sdk/ownership.rb

@@ -6,7 +6,7 @@ require_relative 'config'
 require_relative 'errors'
 require_relative 'key_vault'
 
-module Robocap
+module RobocapCenc
   module SDK
     VerifiedKeyVersion = Data.define(:customer_id, :matched_rsa_key_version, :public_fingerprint)
 

data/lib/robocap/sdk/rsa_delete.rb

@@ -4,7 +4,7 @@ require 'pathname'
 require_relative 'config'
 require_relative 'key_vault'
 
-module Robocap
+module RobocapCenc
   module SDK
     DeleteRsaResult = Data.define(:customer_id, :folder_name, :key_dir)
 

data/lib/robocap/sdk/rsa_import.rb

@@ -5,7 +5,7 @@ require_relative 'config'
 require_relative 'key_vault'
 require_relative 'rsa_key_meta'
 
-module Robocap
+module RobocapCenc
   module SDK
     ImportRsaResult = Data.define(:customer_id, :rsa_key_version, :vault_rsa_dir)
 

data/lib/robocap/sdk/rsa_key_meta.rb

@@ -4,7 +4,7 @@ require 'json'
 require 'time'
 require_relative 'config'
 
-module Robocap
+module RobocapCenc
   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)

data/lib/robocap/sdk/rsa_oaep.rb

@@ -5,7 +5,7 @@ require 'securerandom'
 require_relative 'config'
 require_relative 'errors'
 
-module Robocap
+module RobocapCenc
   module SDK
     module RSAOAEP
       module_function

data/lib/robocap/sdk/vault_layout.rb

@@ -5,7 +5,7 @@ require 'pathname'
 require 'tempfile'
 require_relative 'errors'
 
-module Robocap
+module RobocapCenc
   module SDK
     module VaultLayout
       module_function

data/lib/robocap/sdk/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-module Robocap
+module RobocapCenc
   module SDK
-    VERSION = '1.0.0'
+    VERSION = '2.1.0'
   end
 end

data/lib/robocap/sdk.rb

@@ -14,7 +14,7 @@ require_relative 'sdk/rsa_import'
 require_relative 'sdk/rsa_delete'
 require_relative 'sdk/decrypt_cenc'
 
-module Robocap
+module RobocapCenc
   module SDK
     module_function
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: robocap-decryption-sdk
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Frodobots