carddb 0.4.2 → 0.4.5

data/lib/carddb/collection.rb

@@ -1961,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']
@@ -2056,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'])
@@ -2093,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)
 

data/lib/carddb/query_builder.rb

@@ -968,8 +968,8 @@ module CardDB
 
       def deck
         <<~GRAPHQL
-          query Deck($id: UUID!) {
-            deck(id: $id) {
+          query Deck($id: UUID!, $readState: DeckReadState!, $version: DeckPublishedVersionSelector) {
+            deck(id: $id, readState: $readState, version: $version) {
               #{deck_fields}
             }
           }
@@ -1021,8 +1021,8 @@ module CardDB
 
       def deck_by_external_ref
         <<~GRAPHQL
-          query DeckByExternalRef($externalRef: String!) {
-            deckByExternalRef(externalRef: $externalRef) {
+          query DeckByExternalRef($externalRef: String!, $readState: DeckReadState!, $version: DeckPublishedVersionSelector) {
+            deckByExternalRef(externalRef: $externalRef, readState: $readState, version: $version) {
               #{deck_fields}
             }
           }
@@ -1053,37 +1053,6 @@ module CardDB
         GRAPHQL
       end
 
-      # Builds a deckPreview query
-      def deck_preview
-        <<~GRAPHQL
-          query DeckPreview($token: String!) {
-            deckPreview(token: $token) {
-              #{deck_fields}
-            }
-          }
-        GRAPHQL
-      end
-
-      def deck_embed
-        <<~GRAPHQL
-          query DeckEmbed($token: String!) {
-            deckEmbed(token: $token) {
-              #{deck_fields}
-            }
-          }
-        GRAPHQL
-      end
-
-      def deck_access
-        <<~GRAPHQL
-          query DeckAccess($token: String!) {
-            deckAccess(token: $token) {
-              #{deck_fields}
-            }
-          }
-        GRAPHQL
-      end
-
       def deck_draft_diff
         <<~GRAPHQL
           query DeckDraftDiff($id: UUID!) {
@@ -1163,37 +1132,6 @@ module CardDB
         GRAPHQL
       end
 
-      # Builds a deckPreviewTokens query
-      def deck_preview_tokens
-        <<~GRAPHQL
-          query DeckPreviewTokens($deckId: UUID!) {
-            deckPreviewTokens(deckId: $deckId) {
-              #{deck_preview_token_fields}
-            }
-          }
-        GRAPHQL
-      end
-
-      def deck_embed_tokens
-        <<~GRAPHQL
-          query DeckEmbedTokens($deckId: UUID!) {
-            deckEmbedTokens(deckId: $deckId) {
-              #{deck_embed_token_fields}
-            }
-          }
-        GRAPHQL
-      end
-
-      def deck_access_token_issuers
-        <<~GRAPHQL
-          query DeckAccessTokenIssuers($deckId: UUID!) {
-            deckAccessTokenIssuers(deckId: $deckId) {
-              #{deck_access_token_issuer_fields}
-            }
-          }
-        GRAPHQL
-      end
-
       def deck_api_application_accesses
         <<~GRAPHQL
           query DeckApiApplicationAccesses($deckId: UUID!, $includeRevoked: Boolean) {
@@ -1485,119 +1423,51 @@ module CardDB
         GRAPHQL
       end
 
-      # Builds a deckPreviewTokenCreate mutation
-      def create_deck_preview_token
-        <<~GRAPHQL
-          mutation DeckPreviewTokenCreate($input: DeckPreviewTokenCreateInput!) {
-            deckPreviewTokenCreate(input: $input) {
-              token
-              previewToken {
-                #{deck_preview_token_fields}
-              }
-            }
-          }
-        GRAPHQL
-      end
-
-      # Builds a deckPreviewTokenRevoke mutation
-      def revoke_deck_preview_token
-        <<~GRAPHQL
-          mutation DeckPreviewTokenRevoke($id: UUID!) {
-            deckPreviewTokenRevoke(id: $id)
-          }
-        GRAPHQL
-      end
-
-      def create_deck_embed_token
-        <<~GRAPHQL
-          mutation DeckEmbedTokenCreate($input: DeckEmbedTokenCreateInput!) {
-            deckEmbedTokenCreate(input: $input) {
-              token
-              embedToken {
-                #{deck_embed_token_fields}
-              }
-            }
-          }
-        GRAPHQL
-      end
-
-      def revoke_deck_embed_token
-        <<~GRAPHQL
-          mutation DeckEmbedTokenRevoke($id: UUID!) {
-            deckEmbedTokenRevoke(id: $id)
-          }
-        GRAPHQL
-      end
-
-      def create_deck_access_token_issuer
+      def create_deck_token_issuer
         <<~GRAPHQL
-          mutation DeckAccessTokenIssuerCreate($input: DeckAccessTokenIssuerCreateInput!) {
-            deckAccessTokenIssuerCreate(input: $input) {
-              #{deck_access_token_issuer_fields}
+          mutation DeckTokenIssuerCreate($input: DeckTokenIssuerCreateInput!) {
+            deckTokenIssuerCreate(input: $input) {
+              #{deck_token_issuer_fields}
             }
           }
         GRAPHQL
       end
 
-      def revoke_deck_access_token_issuer
+      def revoke_deck_token_issuer
         <<~GRAPHQL
-          mutation DeckAccessTokenIssuerRevoke($id: UUID!) {
-            deckAccessTokenIssuerRevoke(id: $id)
+          mutation DeckTokenIssuerRevoke($id: UUID!) {
+            deckTokenIssuerRevoke(id: $id)
           }
         GRAPHQL
       end
 
-      def revoke_deck_access_token_issuer_signing_key
+      def revoke_deck_token_issuer_signing_key
         <<~GRAPHQL
-          mutation DeckAccessTokenIssuerSigningKeyRevoke($id: UUID!) {
-            deckAccessTokenIssuerSigningKeyRevoke(id: $id) {
-              #{deck_access_token_issuer_fields}
+          mutation DeckTokenIssuerSigningKeyRevoke($id: UUID!) {
+            deckTokenIssuerSigningKeyRevoke(id: $id) {
+              #{deck_token_issuer_fields}
             }
           }
         GRAPHQL
       end
 
-      def exchange_deck_access_token
+      def exchange_deck_token
         <<~GRAPHQL
-          mutation DeckAccessTokenExchange($input: DeckAccessTokenExchangeInput!) {
-            deckAccessTokenExchange(input: $input) {
+          mutation DeckTokenExchange($input: DeckTokenExchangeInput!) {
+            deckTokenExchange(input: $input) {
               token
-              accessToken {
-                #{deck_access_token_fields}
+              deckToken {
+                #{deck_token_fields}
               }
             }
           }
         GRAPHQL
       end
 
-      def exchange_deck_session_token
+      def revoke_deck_token
         <<~GRAPHQL
-          mutation DeckSessionTokenExchange($input: DeckSessionTokenExchangeInput!) {
-            deckSessionTokenExchange(input: $input) {
-              token
-              sessionToken {
-                id
-                accountId
-                apiApplicationId
-                gameId
-                environment
-                externalSubject
-                scopes
-                expiresAt
-                revokedAt
-                lastUsedAt
-                createdAt
-                updatedAt
-              }
-            }
-          }
-        GRAPHQL
-      end
-
-      def revoke_deck_access_token
-        <<~GRAPHQL
-          mutation DeckAccessTokenRevoke($id: UUID!) {
-            deckAccessTokenRevoke(id: $id)
+          mutation DeckTokenRevoke($id: UUID!) {
+            deckTokenRevoke(id: $id)
           }
         GRAPHQL
       end
@@ -2938,43 +2808,13 @@ module CardDB
         FIELDS
       end
 
-      def deck_preview_token_fields
-        <<~FIELDS
-          id
-          deckId
-          label
-          expiresAt
-          revokedAt
-          lastUsedAt
-          createdAt
-          updatedAt
-        FIELDS
-      end
-
-      def deck_embed_token_fields
+      def deck_token_issuer_fields
         <<~FIELDS
           id
-          deckId
           apiApplicationId
           label
-          readMode
-          allowedOrigins
-          externalSubject
-          expiresAt
-          revokedAt
-          lastUsedAt
-          createdAt
-          updatedAt
-        FIELDS
-      end
-
-      def deck_access_token_issuer_fields
-        <<~FIELDS
-          id
-          deckId
-          apiApplicationId
-          label
-          readModes
+          allowedScopes
+          allowedRepresentations
           maxTokenLifetimeSeconds
           directSigningAlg
           directSigningKeyId
@@ -2986,14 +2826,16 @@ module CardDB
         FIELDS
       end
 
-      def deck_access_token_fields
+      def deck_token_fields
         <<~FIELDS
           id
-          deckId
           apiApplicationId
           issuerId
-          readMode
+          deckId
+          gameId
           externalSubject
+          scopes
+          representation
           expiresAt
           revokedAt
           lastUsedAt