robocap-decryption-sdk 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 024c14dc83b71450c45bd140f4df42fcfacda47f71d4f04edf56d8989e768dd2
-  data.tar.gz: 55c76d3298de9561d29a8a877e017f7157dec1b17b5d6c22486b17719ab11a13
+  metadata.gz: 79e885213cb75dc85172a8a8c8eb17baa9b3684ee6dff10e331d3e6262c2aefe
+  data.tar.gz: 84077253d5bf58dcf7c658512efc7274bf13c3cf6e30eaa87549ef0f73fa99e0
 SHA512:
-  metadata.gz: f26a53d8ec725d1c8ded062db1ba81a5dcb86de1848de0adb3261213c6616067c997cca2605b804057101a07d37fa0e94fa6208d87ecf5bf3b944ac51a12c427
-  data.tar.gz: e0bd269cb297024bb493437a26c9b5eb52b8058b94a0dce5edcd497e0453c959be134608102710b5e94af3fade04e48ff1d979317f2be159f2a69daa0ca90f0d
+  metadata.gz: 1ada52a6ef96f5a2a0726e97365b48c6f0452e84f09d5916269aacc94fc8e3fedfdc8da924396baff5fb45aafe9ed5aad6a364684b31357425491895bd02d7eb
+  data.tar.gz: 449d464f2324500cd1409ed6b3d42dcaa639b2d482614db00432671e2a8afc33393711534db9ad9c7cc8f56222dee130a14fae582e8da96ad1836d150367b371

data/README.md

@@ -42,6 +42,30 @@ 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::*`.

data/lib/robocap/sdk/decrypt_cenc.rb

@@ -16,12 +16,18 @@ module RobocapCenc
     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

@@ -33,6 +33,7 @@ module RobocapCenc
       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/mp4_cenc.rb

@@ -9,12 +9,30 @@ require_relative 'ffmpeg_cli'
 
 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 RobocapCenc
         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 RobocapCenc
           )
         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 RobocapCenc
         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 RobocapCenc
           )
         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 RobocapCenc
               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/version.rb

@@ -2,6 +2,6 @@
 
 module RobocapCenc
   module SDK
-    VERSION = '2.0.0'
+    VERSION = '2.1.0'
   end
 end

metadata

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