carddb 0.4.1 → 0.4.5

data/lib/carddb/collection.rb

@@ -1067,8 +1067,14 @@ module CardDB
     def job_count = data['jobCount']
     def completed_jobs = data['completedJobs']
     def failed_jobs = data['failedJobs']
+    def no_match_count = data['noMatchCount']
     def average_confidence = data['averageConfidence']
     def average_shortlist_size = data['averageShortlistSize']
+    def vector_query_count = data['vectorQueryCount']
+    def vector_fallback_count = data['vectorFallbackCount']
+    def average_vector_candidates = data['averageVectorCandidates']
+    def average_vector_query_ms = data['averageVectorQueryMs']
+    def average_embedding_ms = data['averageEmbeddingMs']
     def feedback_count = data['feedbackCount']
     def correct_feedback = data['correctFeedback']
     def corrected_feedback = data['correctedFeedback']
@@ -1086,7 +1092,14 @@ module CardDB
     def completed_jobs = data['completedJobs']
     def failed_jobs = data['failedJobs']
     def failure_rate = data['failureRate']
+    def no_match_count = data['noMatchCount']
+    def no_match_rate = data['noMatchRate']
     def average_shortlist_size = data['averageShortlistSize']
+    def vector_query_count = data['vectorQueryCount']
+    def vector_fallback_count = data['vectorFallbackCount']
+    def average_vector_candidates = data['averageVectorCandidates']
+    def average_vector_query_ms = data['averageVectorQueryMs']
+    def average_embedding_ms = data['averageEmbeddingMs']
     def confidence_distribution = data['confidenceDistribution'] || {}
 
     def feedback
@@ -1948,91 +1961,12 @@ module CardDB
     def updated_at = parse_time(data['updatedAt'])
   end
 
-  # Wrapper for deck preview token metadata
-  class DeckPreviewToken < Resource
-    def id
-      data['id']
-    end
-
-    def deck_id
-      data['deckId']
-    end
-
-    def label
-      data['label']
-    end
-
-    def expires_at
-      parse_time(data['expiresAt'])
-    end
-
-    def revoked_at
-      parse_time(data['revokedAt'])
-    end
-
-    def last_used_at
-      parse_time(data['lastUsedAt'])
-    end
-
-    def created_at
-      parse_time(data['createdAt'])
-    end
-
-    def updated_at
-      parse_time(data['updatedAt'])
-    end
-
-    private
-
-    def parse_time(value)
-      return nil unless value
-
-      Time.parse(value)
-    rescue ArgumentError
-      value
-    end
-  end
-
-  # Wrapper for deck preview token creation payloads
-  class DeckPreviewTokenCreatePayload < Resource
-    def token
-      data['token']
-    end
-
-    def preview_token
-      @preview_token ||= data['previewToken'] ? DeckPreviewToken.new(data['previewToken'], client: client) : nil
-    end
-  end
-
-  class DeckEmbedToken < Resource
+  class DeckTokenIssuer < Resource
     def id = data['id']
-    def deck_id = data['deckId']
     def api_application_id = data['apiApplicationId']
     def label = data['label']
-    def read_mode = data['readMode']
-    def allowed_origins = data['allowedOrigins'] || []
-    def external_subject = data['externalSubject']
-    def expires_at = parse_time(data['expiresAt'])
-    def revoked_at = parse_time(data['revokedAt'])
-    def last_used_at = parse_time(data['lastUsedAt'])
-    def created_at = parse_time(data['createdAt'])
-    def updated_at = parse_time(data['updatedAt'])
-  end
-
-  class DeckEmbedTokenCreatePayload < Resource
-    def token = data['token']
-
-    def embed_token
-      @embed_token ||= data['embedToken'] ? DeckEmbedToken.new(data['embedToken'], client: client) : nil
-    end
-  end
-
-  class DeckAccessTokenIssuer < Resource
-    def id = data['id']
-    def deck_id = data['deckId']
-    def api_application_id = data['apiApplicationId']
-    def label = data['label']
-    def read_modes = data['readModes'] || []
+    def allowed_scopes = data['allowedScopes'] || []
+    def allowed_representations = data['allowedRepresentations'] || []
     def max_token_lifetime_seconds = data['maxTokenLifetimeSeconds']
     def direct_signing_alg = data['directSigningAlg']
     def direct_signing_key_id = data['directSigningKeyId']
@@ -2043,36 +1977,15 @@ module CardDB
     def updated_at = parse_time(data['updatedAt'])
   end
 
-  class DeckAccessToken < Resource
+  class DeckToken < Resource
     def id = data['id']
-    def deck_id = data['deckId']
     def api_application_id = data['apiApplicationId']
     def issuer_id = data['issuerId']
-    def read_mode = data['readMode']
-    def external_subject = data['externalSubject']
-    def expires_at = parse_time(data['expiresAt'])
-    def revoked_at = parse_time(data['revokedAt'])
-    def last_used_at = parse_time(data['lastUsedAt'])
-    def created_at = parse_time(data['createdAt'])
-    def updated_at = parse_time(data['updatedAt'])
-  end
-
-  class DeckAccessTokenExchangePayload < Resource
-    def token = data['token']
-
-    def access_token
-      @access_token ||= data['accessToken'] ? DeckAccessToken.new(data['accessToken'], client: client) : nil
-    end
-  end
-
-  class DeckSessionToken < Resource
-    def id = data['id']
-    def account_id = data['accountId']
-    def api_application_id = data['apiApplicationId']
+    def deck_id = data['deckId']
     def game_id = data['gameId']
-    def environment = data['environment']
     def external_subject = data['externalSubject']
     def scopes = data['scopes'] || []
+    def representation = data['representation']
     def expires_at = parse_time(data['expiresAt'])
     def revoked_at = parse_time(data['revokedAt'])
     def last_used_at = parse_time(data['lastUsedAt'])
@@ -2080,11 +1993,11 @@ module CardDB
     def updated_at = parse_time(data['updatedAt'])
   end
 
-  class DeckSessionTokenExchangePayload < Resource
+  class DeckTokenExchangePayload < Resource
     def token = data['token']
 
-    def session_token
-      @session_token ||= data['sessionToken'] ? DeckSessionToken.new(data['sessionToken'], client: client) : nil
+    def deck_token
+      @deck_token ||= data['deckToken'] ? DeckToken.new(data['deckToken'], client: client) : nil
     end
   end
 

data/lib/carddb/deck_tokens.rb

@@ -6,25 +6,19 @@ require 'json'
 require 'openssl'
 
 module CardDB
-  # Server-side helpers for minting direct signed deck access tokens.
+  # Server-side helpers for minting direct signed deck tokens.
   module DeckTokens
-    TOKEN_USE = 'carddb.deck_access.v1'
-    AUDIENCE = 'carddb.deck_access'
+    TOKEN_USE = 'carddb.deck_token.v1'
+    AUDIENCE = 'carddb.deck'
     ED25519_PKCS8_PREFIX = [
       '302e020100300506032b657004220420'
     ].pack('H*').freeze
-    READ_MODES = {
-      'PUBLIC' => 'public',
-      'EMBED' => 'embed',
-      'FULL' => 'full'
-    }.freeze
-    private_constant :READ_MODES
 
     class << self
-      # Generate an Ed25519 keypair for CardDB direct deck access token signing.
+      # Generate an Ed25519 keypair for CardDB direct deck token signing.
       #
       # @return [Hash{Symbol => String}] Includes a PEM private key and the base64-encoded raw public key
-      def generate_direct_access_key_pair
+      def generate_direct_key_pair
         signing_key = Ed25519::SigningKey.generate
 
         {
@@ -33,43 +27,31 @@ module CardDB
         }
       end
 
-      # Sign a direct deck access token that CardDB can verify with the issuer public key.
+      # Sign a direct deck token that CardDB can verify with the issuer public key.
       #
       # @param issuer_id [String]
-      # @param deck_id [String]
       # @param api_application_id [String]
       # @param key_id [String]
       # @param private_key [OpenSSL::PKey::PKey, String] Ed25519 private key as an OpenSSL key or PEM/DER string
-      # @param read_mode [String] PUBLIC, EMBED, or FULL
+      # @param deck_id [String, nil]
+      # @param publisher_slug [String, nil]
+      # @param game_key [String, nil]
+      # @param external_subject [String, nil]
+      # @param scopes [Array<String>]
+      # @param representation [String, nil]
       # @param subject [String, nil]
       # @param token_id [String, nil]
       # @param issued_at [Time]
       # @param expires_at [Time]
       # @return [String]
       # @raise [ArgumentError]
-      def sign_direct_access_token(issuer_id:, deck_id:, api_application_id:, key_id:, private_key:, read_mode:,
-                                   expires_at:, subject: nil, token_id: nil, issued_at: Time.now)
-        issued_at, expires_at = validate_signing_input!(
-          issuer_id: issuer_id,
-          deck_id: deck_id,
-          api_application_id: api_application_id,
-          key_id: key_id,
-          issued_at: issued_at,
-          expires_at: expires_at
-        )
-        normalized_read_mode = normalize_read_mode!(read_mode)
-        key = normalize_private_key!(private_key)
-        header = { alg: 'EdDSA', kid: key_id.strip }
-        payload = build_payload(
-          issuer_id: issuer_id,
-          deck_id: deck_id,
-          api_application_id: api_application_id,
-          read_mode: normalized_read_mode,
-          subject: subject,
-          token_id: token_id,
-          issued_at: issued_at,
-          expires_at: expires_at
-        )
+      def sign_direct_token(**attributes)
+        attributes = validate_signing_input!(attributes)
+        normalized_scopes = normalize_scopes!(attributes[:scopes])
+        validate_token_target!(attributes)
+        key = normalize_private_key!(attributes[:private_key])
+        header = { alg: 'EdDSA', kid: attributes[:key_id].strip }
+        payload = build_payload(attributes.merge(scopes: normalized_scopes))
 
         encoded_header = base64url_encode(JSON.generate(header))
         encoded_payload = base64url_encode(JSON.generate(payload))
@@ -81,33 +63,52 @@ module CardDB
 
       private
 
-      def validate_signing_input!(issuer_id:, deck_id:, api_application_id:, key_id:, issued_at:, expires_at:)
-        validate_required_string!(issuer_id, 'issuer_id')
-        validate_required_string!(deck_id, 'deck_id')
-        validate_required_string!(api_application_id, 'api_application_id')
-        validate_required_string!(key_id, 'key_id')
+      def validate_signing_input!(attributes)
+        validate_known_keys!(attributes)
+        attributes = { issued_at: Time.now }.merge(attributes)
+        validate_required_string!(attributes[:issuer_id], 'issuer_id')
+        validate_required_string!(attributes[:api_application_id], 'api_application_id')
+        validate_required_string!(attributes[:key_id], 'key_id')
 
-        issued_at = normalize_time!(issued_at, 'issued_at')
-        expires_at = normalize_time!(expires_at, 'expires_at')
+        issued_at = normalize_time!(attributes[:issued_at], 'issued_at')
+        expires_at = normalize_time!(attributes[:expires_at], 'expires_at')
         raise ArgumentError, 'expires_at must be after issued_at' unless expires_at > issued_at
 
-        [issued_at, expires_at]
+        attributes.merge(issued_at: issued_at, expires_at: expires_at)
       end
 
-      def build_payload(issuer_id:, deck_id:, api_application_id:, read_mode:, subject:, token_id:, issued_at:,
-                        expires_at:)
+      def validate_known_keys!(attributes)
+        allowed_keys = %i[
+          issuer_id api_application_id key_id private_key scopes expires_at deck_id publisher_slug game_key
+          external_subject representation subject token_id issued_at
+        ]
+        unknown_keys = attributes.keys - allowed_keys
+        return if unknown_keys.empty?
+
+        raise ArgumentError, "unknown keyword: :#{unknown_keys.first}"
+      end
+
+      def build_payload(attributes)
         payload = {
           token_use: TOKEN_USE,
-          deck_id: deck_id.strip,
-          app_id: api_application_id.strip,
-          read_mode: read_mode,
-          iss: issuer_id.strip,
+          app_id: attributes[:api_application_id].strip,
+          scopes: attributes[:scopes],
+          iss: attributes[:issuer_id].strip,
           aud: AUDIENCE,
-          iat: issued_at.to_i,
-          exp: expires_at.to_i
+          iat: attributes[:issued_at].to_i,
+          exp: attributes[:expires_at].to_i
         }
-        add_optional_claim!(payload, :sub, subject)
-        add_optional_claim!(payload, :jti, token_id)
+        {
+          deck_id: :deck_id,
+          publisher_slug: :publisher_slug,
+          game_key: :game_key,
+          external_subject: :external_subject,
+          representation: :representation,
+          sub: :subject,
+          jti: :token_id
+        }.each do |claim, key|
+          add_optional_claim!(payload, claim, attributes[key])
+        end
         payload
       end
 
@@ -120,18 +121,32 @@ module CardDB
         raise ArgumentError, "#{name} is required" unless value.is_a?(String) && !value.strip.empty?
       end
 
+      def normalize_scopes!(scopes)
+        raise ArgumentError, 'scopes must include at least one DeckTokenScope' unless scopes.is_a?(Array) && !scopes.empty?
+
+        scopes.map do |scope|
+          validate_required_string!(scope, 'scope')
+          scope.strip
+        end
+      end
+
+      def validate_token_target!(attributes)
+        return if string_present?(attributes[:deck_id])
+        return if %i[publisher_slug game_key external_subject].all? { |key| string_present?(attributes[key]) }
+
+        raise ArgumentError, 'deck_id or publisher_slug, game_key, and external_subject are required'
+      end
+
+      def string_present?(value)
+        value&.strip&.length&.positive?
+      end
+
       def normalize_time!(value, name)
         raise ArgumentError, "#{name} must be a Time" unless value.is_a?(Time)
 
         value
       end
 
-      def normalize_read_mode!(read_mode)
-        READ_MODES.fetch(read_mode.to_s.upcase) do
-          raise ArgumentError, 'read_mode must be PUBLIC, EMBED, or FULL'
-        end
-      end
-
       def normalize_private_key!(private_key)
         return private_key if private_key.is_a?(OpenSSL::PKey::PKey)