accessgrid 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05f4bc4f464d21efa501041653ae1252c64f6d5cca1a29b30394b51ea0cdd486
-  data.tar.gz: e26bba2fb9ccb37ecfaa5f32676453c9b5a5369b49d11f6cc2385a26345eead6
+  metadata.gz: 5370a4fedb6bf2bb2dc99ec4a8b28148f1caca417aca9f2401192c06a5fd49f9
+  data.tar.gz: fbe42537ec52fef71f1cd9806f2d91896c65e8e2ae4ad08aa8b9b864c52cf6aa
 SHA512:
-  metadata.gz: 181d498ca94e2514ecf4c5296acf2b4cb5d975efbd77cfa0915280dcc610b7860740cb58ad1d3909f5ca137a30ca610347e10de6d85608c72fbe022e31923eb4
-  data.tar.gz: d9ccd5c9bf41ba8f68415ea1ad9f72b68b48fa2799f76ce53726cd3fca93466a56e38fe6320b907c57cb67dbb7f8aac06674cd7cba7ac97a31ab44fb32d6ea11
+  metadata.gz: c98e6d776bd2eede74712e6a6a08d0b87c67cc2161dc18748d84db28f34273b69aa6f8f2ce4d6bdb0a5f02c6a68a60cf1b043bed9a785402a373a3296e72521e
+  data.tar.gz: 6d8c089a3071b4064a5902823cfd8f88393fd0d60d80215a72860dd6e139d1a790b4a8a5b410a3311d54915b6a6c1fe94c7c3cc023d33c0a74691e2c886c1a1d

data/README.md

@@ -139,7 +139,7 @@ client.access_cards.delete("0xc4rd1d")
 template = client.console.create_template(
   name: "Employee Access Pass",
   platform: "apple",
-  use_case: "employee_badge",
+  use_case: "corporate_id",
   protocol: "desfire",
   allow_on_multiple_devices: true,
   watch_count: 2,
@@ -185,6 +185,30 @@ template = client.console.update_template(
 template = client.console.read_template("0xd3adb00b5")
 ```
 
+#### Publish a template
+
+```ruby
+result = client.console.publish_template("0xd3adb00b5")
+
+puts result.id      # "0xd3adb00b5"
+puts result.status  # "in-review" (Apple), "ready" (Android), or "publishing" (already in flight)
+```
+
+#### Reveal a SmartTap private key
+
+Fetches the template's SmartTap private key, decrypted client-side. The SDK generates a fresh ephemeral P-256 keypair per call, submits the public half, and decrypts the server's response — you get the plaintext PEM back without touching any crypto.
+
+```ruby
+reveal = client.console.reveal_smart_tap("0xd3adb00b5")
+
+puts "Key version:  #{reveal.key_version}"
+puts "Collector ID: #{reveal.collector_id}"
+puts "Fingerprint:  #{reveal.fingerprint}"
+puts reveal.private_key  # PEM — store in your reader/collector key vault
+```
+
+The server enforces single-use on pubkey fingerprint and rate-limits to 1 per minute per account. The SDK uses a fresh keypair every call, so single-use is satisfied automatically. Errors raised by the crypto path (`AccessGrid::DecryptError`, `AccessGrid::InvalidEnvelopeError`) and the HTTP path (`AccessGrid::AuthenticationError`, `AccessGrid::ResourceNotFoundError`, etc.) all descend from `AccessGrid::Error`.
+
 #### Get event logs
 
 ```ruby
@@ -480,6 +504,8 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/access
 | GET /v1/console/card-template-pairs | `console.list_pass_template_pairs()` | Y |
 | POST /v1/console/card-template-pairs | `console.create_pass_template_pair()` | Y |
 | POST /v1/console/card-templates/{id}/ios_preflight | `console.ios_preflight()` | Y |
+| POST /v1/console/card-templates/{id}/publish | `console.publish_template()` | Y |
+| POST /v1/console/card-templates/{id}/smart-tap/reveal | `console.reveal_smart_tap()` | Y |
 | GET /v1/console/ledger-items | `console.list_ledger_items()` / `console.ledger_items()` | Y |
 | GET /v1/console/webhooks | `console.webhooks.list()` | Y |
 | POST /v1/console/webhooks | `console.webhooks.create()` | Y |

data/lib/accessgrid/console.rb

@@ -73,6 +73,29 @@ module AccessGrid
 
     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)
@@ -188,6 +211,30 @@ module AccessGrid
     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

data/lib/accessgrid/error.rb

@@ -13,6 +13,15 @@ module AccessGrid
   # 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

@@ -82,7 +82,7 @@ module AccessGrid
 
       last_part = parts.last
       second_to_last_part = parts[-2]
-      @resource_id = %w[suspend resume unlink delete].include?(last_part) ? second_to_last_part : last_part
+      @resource_id = %w[suspend resume unlink delete publish].include?(last_part) ? second_to_last_part : last_part
     end
 
     def get?

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

@@ -2,5 +2,5 @@
 
 # lib/accessgrid/version.rb
 module AccessGrid
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

data/lib/accessgrid.rb

@@ -11,6 +11,7 @@ require_relative 'accessgrid/access_cards'
 require_relative 'accessgrid/console'
 require_relative 'accessgrid/error'
 require_relative 'accessgrid/request'
+require_relative 'accessgrid/smart_tap_reveal_crypto'
 require_relative 'accessgrid/version'
 
 # Ruby SDK for the AccessGrid API.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: accessgrid
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Auston Bunsen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-16 00:00:00.000000000 Z
+date: 2026-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -38,6 +38,7 @@ files:
 - lib/accessgrid/console.rb
 - lib/accessgrid/error.rb
 - lib/accessgrid/request.rb
+- lib/accessgrid/smart_tap_reveal_crypto.rb
 - lib/accessgrid/version.rb
 homepage: https://github.com/access-grid/accessgrid-rb
 licenses:
@@ -59,7 +60,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
+rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
 summary: AccessGrid API Client