accessgrid 0.2.0 → 0.5.0

data/lib/accessgrid/console.rb

@@ -1,8 +1,16 @@
+# frozen_string_literal: true
+
 # lib/accessgrid/console.rb
 module AccessGrid
+  # Manages enterprise template and logging operations.
   class Console
+    attr_reader :webhooks, :hid, :credential_profiles
+
     def initialize(client)
       @client = client
+      @webhooks = Webhooks.new(client)
+      @hid = HID.new(client)
+      @credential_profiles = CredentialProfiles.new(client)
     end
 
     def create_template(params)
@@ -24,15 +32,13 @@ module AccessGrid
 
     def get_logs(template_id, params = {})
       response = @client.make_request(:get, "/v1/console/card-templates/#{template_id}/logs", nil, params)
-      
+
       # Return full response to match Python's behavior
-      if response['logs']
-        response['logs'] = response['logs'].map { |log| Event.new(log) }
-      end
-      
+      response['logs'] = response['logs'].map { |log| Event.new(log) } if response['logs']
+
       response
     end
-    
+
     # Keep event_log for backwards compatibility
     def event_log(params)
       template_id = params.delete(:card_template_id)
@@ -40,29 +46,98 @@ module AccessGrid
       response['logs'] || []
     end
 
+    def list_pass_template_pairs(params = {})
+      response = @client.make_request(:get, '/v1/console/card-template-pairs', nil, params)
+
+      if response['card_template_pairs']
+        response['card_template_pairs'] = response['card_template_pairs'].map { |pair| PassTemplatePair.new(pair) }
+      end
+
+      response
+    end
+
+    def create_pass_template_pair(params)
+      response = @client.make_request(:post, '/v1/console/card-template-pairs', params)
+      PassTemplatePair.new(response)
+    end
+
+    def list_ledger_items(params = {})
+      response = @client.make_request(:get, '/v1/console/ledger-items', nil, params)
+
+      if response['ledger_items']
+        response['ledger_items'] = response['ledger_items'].map { |item| LedgerItem.new(item) }
+      end
+
+      response
+    end
+
+    alias ledger_items list_ledger_items
+
+    def publish_template(template_id)
+      response = @client.make_request(:post, "/v1/console/card-templates/#{template_id}/publish")
+      PublishTemplateResponse.new(response)
+    end
+
+    # Reveal the SmartTap private key for a card template, decrypted client-side.
+    #
+    # The SDK generates a fresh ephemeral P-256 keypair per call, submits the
+    # public half, and decrypts the server's response. The returned
+    # RevealTemplatePrivateKey carries the plaintext PEM in #private_key;
+    # the encrypted envelope is consumed internally and not exposed.
+    def reveal_smart_tap(template_id)
+      keypair = SmartTapRevealCrypto.generate_keypair
+      response = @client.make_request(
+        :post,
+        "/v1/console/card-templates/#{template_id}/smart-tap/reveal",
+        { client_public_key: keypair[:pub_pem] }
+      )
+
+      plaintext = SmartTapRevealCrypto.decrypt_envelope(response['encrypted_private_key'], keypair[:priv])
+      RevealTemplatePrivateKey.new(response.merge('private_key' => plaintext))
+    end
+
+    def ios_preflight(card_template_id:, access_pass_ex_id:)
+      data = { access_pass_ex_id: access_pass_ex_id }
+      response = @client.make_request(:post, "/v1/console/card-templates/#{card_template_id}/ios_preflight", data)
+      IosPreflight.new(response)
+    end
+
+    def list_landing_pages
+      response = @client.make_request(:get, '/v1/console/landing-pages')
+      pages = response.is_a?(Array) ? response : response.fetch('landing_pages', [])
+      pages.map { |page| LandingPage.new(page) }
+    end
+
+    def create_landing_page(**params)
+      response = @client.make_request(:post, '/v1/console/landing-pages', params)
+      LandingPage.new(response)
+    end
+
+    def update_landing_page(landing_page_id:, **params)
+      response = @client.make_request(:put, "/v1/console/landing-pages/#{landing_page_id}", params)
+      LandingPage.new(response)
+    end
+
     private
 
     def transform_template_params(params)
-      design = params.delete(:design) || {}
-      support_info = params.delete(:support_info) || {}
-      
-      params.merge(
-        background_color: design[:background_color],
-        label_color: design[:label_color],
-        label_secondary_color: design[:label_secondary_color],
-        support_url: support_info[:support_url],
-        support_phone_number: support_info[:support_phone_number],
-        support_email: support_info[:support_email],
-        privacy_policy_url: support_info[:privacy_policy_url],
-        terms_and_conditions_url: support_info[:terms_and_conditions_url]
-      )
+      design = params.delete(:design)
+      support_info = params.delete(:support_info)
+
+      # Only merge nested keys if they were provided (backward compat)
+      params.merge!(design) if design
+      params.merge!(support_info) if support_info
+
+      params
     end
   end
 
+  # Represents a card template configuration.
   class Template
-    attr_reader :id, :name, :platform, :protocol, :use_case, :created_at, 
+    attr_reader :id, :name, :platform, :protocol, :use_case, :created_at,
                 :last_published_at, :issued_keys_count, :active_keys_count,
-                :allowed_device_counts, :support_settings, :terms_settings, :style_settings
+                :allowed_device_counts, :support_settings, :terms_settings, :style_settings,
+                :metadata
 
     def initialize(data)
       @id = data['id']
@@ -78,19 +153,275 @@ module AccessGrid
       @support_settings = data['support_settings']
       @terms_settings = data['terms_settings']
       @style_settings = data['style_settings']
+      @metadata = data['metadata'] || {}
     end
   end
 
+  # Represents a template activity log event.
   class Event
     attr_reader :type, :timestamp, :user_id, :ip_address, :user_agent, :metadata
 
     def initialize(data)
+      metadata = data['metadata']
       @type = data['event']
       @timestamp = data['created_at']
-      @user_id = data['metadata']['user_id'] if data['metadata'] && data['metadata']['user_id']
+      @user_id = metadata['user_id'] if metadata && metadata['user_id']
       @ip_address = data['ip_address']
       @user_agent = data['user_agent']
+      @metadata = metadata
+    end
+  end
+
+  # Represents a paired iOS and Android template configuration.
+  class PassTemplatePair
+    attr_reader :id, :name, :created_at, :android_template, :ios_template
+
+    def initialize(data)
+      android_template = data['android_template']
+      ios_template = data['ios_template']
+      @id = data['id']
+      @name = data['name']
+      @created_at = data['created_at']
+      @android_template = android_template ? TemplateInfo.new(android_template) : nil
+      @ios_template = ios_template ? TemplateInfo.new(ios_template) : nil
+    end
+  end
+
+  # Minimal template info used within PassTemplatePair.
+  class TemplateInfo
+    attr_reader :id, :name, :platform
+
+    def initialize(data)
+      @id = data['id']
+      @name = data['name']
+      @platform = data['platform']
+    end
+  end
+
+  # Represents an iOS In-App Provisioning preflight response.
+  class IosPreflight
+    attr_reader :provisioning_credential_identifier, :sharing_instance_identifier,
+                :card_template_identifier, :environment_identifier
+
+    def initialize(data)
+      @provisioning_credential_identifier = data['provisioningCredentialIdentifier']
+      @sharing_instance_identifier = data['sharingInstanceIdentifier']
+      @card_template_identifier = data['cardTemplateIdentifier']
+      @environment_identifier = data['environmentIdentifier']
+    end
+  end
+
+  # Result of publishing a card template.
+  class PublishTemplateResponse
+    attr_reader :id, :status
+
+    def initialize(data)
+      @id = data['id']
+      @status = data['status']
+    end
+  end
+
+  # Result of revealing a SmartTap private key. #private_key is the plaintext
+  # PEM, decrypted client-side by the SDK; the encrypted envelope is consumed
+  # internally and not exposed.
+  class RevealTemplatePrivateKey
+    attr_reader :key_version, :collector_id, :fingerprint, :private_key
+
+    def initialize(data)
+      @key_version = data['key_version']
+      @collector_id = data['collector_id']
+      @fingerprint = data['fingerprint']
+      @private_key = data['private_key']
+    end
+  end
+
+  # Represents a billing ledger item.
+  class LedgerItem
+    attr_reader :created_at, :amount, :id, :kind, :metadata, :access_pass
+
+    def initialize(data)
+      @created_at = data['created_at']
+      @amount = data['amount']
+      @id = data['id']
+      @kind = data['kind']
+      @metadata = data['metadata']
+      @access_pass = data['access_pass'] ? LedgerItemAccessPass.new(data['access_pass']) : nil
+    end
+  end
+
+  # Represents an access pass reference within a ledger item.
+  class LedgerItemAccessPass
+    attr_reader :id, :full_name, :state, :metadata, :unified_access_pass_ex_id, :pass_template
+
+    def initialize(data)
+      @id = data['id']
+      @full_name = data['full_name']
+      @state = data['state']
       @metadata = data['metadata']
+      @unified_access_pass_ex_id = data['unified_access_pass_ex_id']
+      @pass_template = data['pass_template'] ? LedgerItemPassTemplate.new(data['pass_template']) : nil
+    end
+  end
+
+  # Represents a pass template reference within a ledger item's access pass.
+  class LedgerItemPassTemplate
+    attr_reader :id, :name, :protocol, :platform, :use_case
+
+    def initialize(data)
+      @id = data['id']
+      @name = data['name']
+      @protocol = data['protocol']
+      @platform = data['platform']
+      @use_case = data['use_case']
+    end
+  end
+
+  # Represents a landing page configuration.
+  class LandingPage
+    attr_reader :id, :name, :created_at, :kind, :password_protected, :logo_url
+
+    def initialize(data)
+      @id = data['id']
+      @name = data['name']
+      @created_at = data['created_at']
+      @kind = data['kind']
+      @password_protected = data['password_protected']
+      @logo_url = data['logo_url']
+    end
+  end
+
+  # Represents a credential profile configuration.
+  class CredentialProfile
+    attr_reader :id, :aid, :name, :apple_id, :created_at, :card_storage, :keys, :files
+
+    def initialize(data)
+      @id = data['id']
+      @aid = data['aid']
+      @name = data['name']
+      @apple_id = data['apple_id']
+      @created_at = data['created_at']
+      @card_storage = data['card_storage']
+      @keys = data['keys'] || []
+      @files = data['files'] || []
+    end
+  end
+
+  # Manages credential profile operations.
+  class CredentialProfiles
+    def initialize(client)
+      @client = client
+    end
+
+    def create(**params)
+      response = @client.make_request(:post, '/v1/console/credential-profiles', params)
+      CredentialProfile.new(response)
+    end
+
+    def list
+      response = @client.make_request(:get, '/v1/console/credential-profiles')
+      profiles = response.is_a?(Array) ? response : response.fetch('credential_profiles', [])
+      profiles.map { |profile| CredentialProfile.new(profile) }
+    end
+  end
+
+  # Manages webhook operations.
+  class Webhooks
+    def initialize(client)
+      @client = client
+    end
+
+    def create(name:, url:, subscribed_events:, auth_method: 'bearer_token')
+      data = {
+        name: name,
+        url: url,
+        subscribed_events: subscribed_events,
+        auth_method: auth_method
+      }
+      response = @client.make_request(:post, '/v1/console/webhooks', data)
+      Webhook.new(response)
+    end
+
+    def list(**params)
+      response = @client.make_request(:get, '/v1/console/webhooks', nil, params)
+      (response['webhooks'] || []).map { |wh| Webhook.new(wh) }
+    end
+
+    def delete(webhook_id)
+      @client.make_request(:delete, "/v1/console/webhooks/#{webhook_id}")
+    end
+  end
+
+  # Represents a webhook configuration.
+  class Webhook
+    attr_reader :id, :name, :url, :auth_method, :subscribed_events,
+                :created_at, :private_key, :client_cert, :cert_expires_at
+
+    def initialize(data)
+      @id = data['id']
+      @name = data['name']
+      @url = data['url']
+      @auth_method = data['auth_method']
+      @subscribed_events = data['subscribed_events']
+      @created_at = data['created_at']
+      @private_key = data['private_key']
+      @client_cert = data['client_cert']
+      @cert_expires_at = data['cert_expires_at']
+    end
+  end
+
+  # Provides access to HID-related services.
+  class HID
+    attr_reader :orgs
+
+    def initialize(client)
+      @orgs = HIDOrgs.new(client)
+    end
+  end
+
+  # Manages HID organization operations.
+  class HIDOrgs
+    def initialize(client)
+      @client = client
+    end
+
+    def create(name:, full_address:, phone:, first_name:, last_name:)
+      data = {
+        name: name,
+        full_address: full_address,
+        phone: phone,
+        first_name: first_name,
+        last_name: last_name
+      }
+      response = @client.make_request(:post, '/v1/console/hid/orgs', data)
+      HidOrg.new(response)
+    end
+
+    def list
+      response = @client.make_request(:get, '/v1/console/hid/orgs')
+      response.map { |org| HidOrg.new(org) }
+    end
+
+    def activate(email:, password:)
+      data = { email: email, password: password }
+      response = @client.make_request(:post, '/v1/console/hid/orgs/activate', data)
+      HidOrg.new(response)
+    end
+  end
+
+  # Represents an HID organization.
+  class HidOrg
+    attr_reader :id, :name, :slug, :first_name, :last_name, :phone, :full_address, :status, :created_at
+
+    def initialize(data)
+      @id = data['id']
+      @name = data['name']
+      @slug = data['slug']
+      @first_name = data['first_name']
+      @last_name = data['last_name']
+      @phone = data['phone']
+      @full_address = data['full_address']
+      @status = data['status']
+      @created_at = data['created_at']
     end
   end
-end
+end

data/lib/accessgrid/error.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module AccessGrid
+  # base error
+  class Error < StandardError; end
+
+  # Raised when API credentials are invalid.
+  class AuthenticationError < Error; end
+
+  # Raised when a requested resource does not exist.
+  class ResourceNotFoundError < Error; end
+
+  # Raised when request parameters fail validation.
+  class ValidationError < Error; end
+
+  # Raised when a SmartTap reveal envelope is missing fields or contains
+  # non-base64 / non-PEM data.
+  class InvalidEnvelopeError < Error; end
+
+  # Raised when AES-GCM auth-tag verification fails while decrypting a
+  # SmartTap reveal envelope (wrong key, tampered envelope, or wire-format
+  # drift between server and SDK).
+  class DecryptError < Error; end
+
+  # additional error classes to match Python version
+  class AccessGridError < Error; end
+end

data/lib/accessgrid/request.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module AccessGrid
+  # Builds and configures HTTP requests for the AccessGrid API.
+  class Request
+    PAYLOAD_SIGNATURE_PARAM = :sig_payload
+    HTTP_METHODS = {
+      get: Net::HTTP::Get,
+      post: Net::HTTP::Post,
+      put: Net::HTTP::Put,
+      patch: Net::HTTP::Patch,
+      delete: Net::HTTP::Delete
+    }.freeze
+
+    attr_reader :account_id, :body, :http_method, :params, :payload, :uri
+
+    def initialize(attrs)
+      # required attributes
+      @http_method = attrs.fetch(:http_method)
+      @provided_host = attrs.fetch(:host)
+      @provided_path = attrs.fetch(:path)
+
+      # optional attributes
+      @account_id = attrs.fetch(:account_id, nil)
+      @body = attrs.fetch(:body, nil)
+      @params = attrs.fetch(:params, nil) || {}
+
+      # computed attributes
+      initialize_payload
+      initialize_uri
+    end
+
+    def net_http_request
+      return @net_http_request if defined?(@net_http_request)
+
+      @net_http_request = generate_net_http_request!.tap do |req|
+        req['Content-Type'] = 'application/json'
+        req['X-ACCT-ID'] = account_id
+        req['User-Agent'] = "accessgrid.rb @ v#{AccessGrid::VERSION}"
+
+        req.body = body.to_json if body && !get?
+      end
+    end
+
+    private
+
+    def generate_net_http_request!
+      klass = HTTP_METHODS.fetch(http_method) do
+        raise ArgumentError, "Unsupported HTTP method: #{http_method}"
+      end
+      klass.new(uri.request_uri)
+    end
+
+    def initialize_payload
+      return @payload if defined?(@payload)
+      return @payload = default_payload unless post_without_body_or_get?
+
+      if resource_id
+        @payload = { id: resource_id }.to_json
+        @params[PAYLOAD_SIGNATURE_PARAM] = @payload
+      else
+        @payload = '{}'
+      end
+
+      @payload
+    end
+
+    def initialize_uri
+      @uri = URI.parse("#{@provided_host}#{@provided_path}").tap do |parsed_uri|
+        parsed_uri.query = URI.encode_www_form(@params) if @params.any?
+      end
+    end
+
+    def resource_id
+      return @resource_id if defined?(@resource_id)
+      return @resource_id = nil unless post_without_body_or_get?
+
+      parts = @provided_path.strip.split('/')
+      return @resource_id = nil unless parts.length >= 2
+
+      last_part = parts.last
+      second_to_last_part = parts[-2]
+      @resource_id = %w[suspend resume unlink delete publish].include?(last_part) ? second_to_last_part : last_part
+    end
+
+    def get?
+      http_method == :get
+    end
+
+    def delete?
+      http_method == :delete
+    end
+
+    def post?
+      http_method == :post
+    end
+
+    def empty_body?
+      body.nil? || body.empty?
+    end
+
+    def post_without_body_or_get?
+      get? || delete? || (post? && empty_body?)
+    end
+
+    def default_payload
+      body&.to_json || ''
+    end
+  end
+end

data/lib/accessgrid/smart_tap_reveal_crypto.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'base64'
+
+module AccessGrid
+  # Internal crypto helpers for the SmartTap reveal flow.
+  #
+  # Driven by Console#reveal_smart_tap; not part of the public SDK surface.
+  # Pure stdlib — no new gem deps.
+  #
+  # @api private
+  module SmartTapRevealCrypto
+    CURVE = 'prime256v1'
+    HKDF_INFO = 'accessgrid-smart-tap-reveal-v1'
+    KEY_LEN = 32
+
+    # Generate a fresh ephemeral P-256 keypair for a reveal call.
+    #
+    # @return [Hash] `{priv: OpenSSL::PKey::EC, pub_pem: String}`
+    def self.generate_keypair
+      priv = OpenSSL::PKey::EC.generate(CURVE)
+      { priv: priv, pub_pem: priv.public_to_pem }
+    end
+
+    # Decrypt the encrypted_private_key envelope from the reveal endpoint.
+    #
+    # Performs ECDH(client_priv, server_ephemeral_pub) + HKDF-SHA256 +
+    # AES-256-GCM. Must match the server-side encryption parameters exactly.
+    #
+    # @return [String] the plaintext SmartTap private key PEM.
+    # @raise [RuntimeError] on missing/bad envelope or auth-tag verification failure.
+    def self.decrypt_envelope(envelope, priv)
+      server_pub = parse_ephemeral_public_key(envelope)
+      nonce = decode_envelope_bytes(envelope['iv'])
+      ciphertext = decode_envelope_bytes(envelope['ciphertext'])
+      tag = decode_envelope_bytes(envelope['tag'])
+
+      aes_key = derive_aes_key(priv, server_pub)
+      aes_gcm_decrypt(aes_key, nonce, ciphertext, tag)
+    end
+
+    # @api private
+    def self.parse_ephemeral_public_key(envelope)
+      pem = envelope['ephemeral_public_key']
+      raise InvalidEnvelopeError, 'Invalid ephemeral_public_key in envelope' unless pem.is_a?(String) && !pem.empty?
+
+      OpenSSL::PKey::EC.new(pem)
+    end
+
+    # @api private
+    def self.derive_aes_key(priv, server_pub)
+      shared_secret = priv.dh_compute_key(server_pub.public_key)
+      OpenSSL::KDF.hkdf(shared_secret, salt: '', info: HKDF_INFO, length: KEY_LEN, hash: 'SHA256')
+    end
+
+    # @api private
+    def self.aes_gcm_decrypt(aes_key, nonce, ciphertext, tag)
+      cipher = OpenSSL::Cipher.new('aes-256-gcm').decrypt
+      cipher.key = aes_key
+      cipher.iv = nonce
+      cipher.auth_tag = tag
+      cipher.auth_data = ''
+      cipher.update(ciphertext) + cipher.final
+    rescue OpenSSL::Cipher::CipherError
+      raise DecryptError, 'AES-GCM decryption failed (auth tag verification)'
+    end
+
+    # @api private
+    def self.decode_envelope_bytes(value)
+      raise InvalidEnvelopeError, 'Envelope iv/ciphertext/tag must be base64-encoded' unless value.is_a?(String)
+
+      Base64.strict_decode64(value)
+    rescue ArgumentError
+      raise InvalidEnvelopeError, 'Envelope iv/ciphertext/tag must be base64-encoded'
+    end
+  end
+end

data/lib/accessgrid/version.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
+
 # lib/accessgrid/version.rb
 module AccessGrid
-  VERSION = '0.2.0'
-end
+  VERSION = '0.5.0'
+end