accessgrid 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05f4bc4f464d21efa501041653ae1252c64f6d5cca1a29b30394b51ea0cdd486
-  data.tar.gz: e26bba2fb9ccb37ecfaa5f32676453c9b5a5369b49d11f6cc2385a26345eead6
+  metadata.gz: 611a55bbec1d43d8241d9d92601bfcaaf0f40e96e2d53330d56668311bc8dfd4
+  data.tar.gz: e9a7fe6162e349464bf93f9cda848e59deb6dc6ff91690be874ec5eab67945e4
 SHA512:
-  metadata.gz: 181d498ca94e2514ecf4c5296acf2b4cb5d975efbd77cfa0915280dcc610b7860740cb58ad1d3909f5ca137a30ca610347e10de6d85608c72fbe022e31923eb4
-  data.tar.gz: d9ccd5c9bf41ba8f68415ea1ad9f72b68b48fa2799f76ce53726cd3fca93466a56e38fe6320b907c57cb67dbb7f8aac06674cd7cba7ac97a31ab44fb32d6ea11
+  metadata.gz: 4b1f579ef34c871ee9f8eea7993d8b67c173dfc3b7c173be75be979f6b008fdfaa07bfc8ddac32de84eab163d4e57a6c193f12369c43be52203c2c180062c43a
+  data.tar.gz: 16771d5080fcf568017272d1f23accaa168cff849fe5c6b2d03b3d992cd661d5548ad3551d69dd1096a3a1bc3fe9354eeae54c4be513fddd2e8d5c6cf08ce7b9

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,36 @@ 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)
+```
+
+#### Delete a template
+
+```ruby
+client.console.delete_template("0xd3adb00b5")
+```
+
+#### 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
@@ -294,6 +324,14 @@ end
 client.console.webhooks.delete('abc123')
 ```
 
+#### Verify a webhook
+
+```ruby
+result = client.console.webhooks.verify('abc123')
+
+puts "Verified: #{result.verified}"
+```
+
 ### HID Organizations
 
 #### Create an HID org
@@ -404,6 +442,12 @@ puts "Profile created: #{profile.id}"
 puts "AID: #{profile.aid}"
 ```
 
+#### Delete a credential profile
+
+```ruby
+client.console.credential_profiles.delete('a1b2c3d4e5f')
+```
+
 ## Configuration
 
 The SDK can be configured with a custom API endpoint:
@@ -480,15 +524,20 @@ 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 |
+| DELETE /v1/console/card-templates/{id} | `console.delete_template()` | 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 |
 | DELETE /v1/console/webhooks/{id} | `console.webhooks.delete()` | Y |
+| POST /v1/console/webhooks/{id}/verify | `console.webhooks.verify()` | Y |
 | GET /v1/console/landing-pages | `console.list_landing_pages()` | Y |
 | POST /v1/console/landing-pages | `console.create_landing_page()` | Y |
 | PUT /v1/console/landing-pages/{id} | `console.update_landing_page()` | Y |
 | GET /v1/console/credential-profiles | `console.credential_profiles.list()` | Y |
 | POST /v1/console/credential-profiles | `console.credential_profiles.create()` | Y |
+| DELETE /v1/console/credential-profiles/{id} | `console.credential_profiles.delete()` | Y |
 | POST /v1/console/hid/orgs | `console.hid.orgs.create()` | Y |
 | POST /v1/console/hid/orgs/activate | `console.hid.orgs.activate()` | Y |
 | GET /v1/console/hid/orgs | `console.hid.orgs.list()` | Y |

data/lib/accessgrid/console.rb

@@ -73,6 +73,33 @@ 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
+
+    def delete_template(template_id)
+      @client.make_request(:delete, "/v1/console/card-templates/#{template_id}")
+    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 +215,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
@@ -275,6 +326,10 @@ module AccessGrid
       profiles = response.is_a?(Array) ? response : response.fetch('credential_profiles', [])
       profiles.map { |profile| CredentialProfile.new(profile) }
     end
+
+    def delete(credential_profile_id)
+      @client.make_request(:delete, "/v1/console/credential-profiles/#{credential_profile_id}")
+    end
   end
 
   # Manages webhook operations.
@@ -302,6 +357,20 @@ module AccessGrid
     def delete(webhook_id)
       @client.make_request(:delete, "/v1/console/webhooks/#{webhook_id}")
     end
+
+    def verify(webhook_id)
+      response = @client.make_request(:post, "/v1/console/webhooks/#{webhook_id}/verify")
+      WebhookVerification.new(response)
+    end
+  end
+
+  class WebhookVerification
+    attr_reader :id, :verified
+
+    def initialize(data)
+      @id = data['id']
+      @verified = data['verified']
+    end
   end
 
   # Represents a webhook configuration.

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,8 @@ 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
+      action_words = %w[suspend resume unlink delete publish verify]
+      @resource_id = action_words.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.6.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,13 @@
 --- !ruby/object:Gem::Specification
 name: accessgrid
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Auston Bunsen
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-16 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -38,13 +37,13 @@ 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:
 - MIT
 metadata:
   source_code_uri: https://github.com/access-grid/accessgrid-rb
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -59,8 +58,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 4.0.3
 specification_version: 4
 summary: AccessGrid API Client
 test_files: []