mobiscroll-connect 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b741101bdf4d7452a820bd7b988d9dff51f02cf4683d867fb332292ab0a4177e
-  data.tar.gz: 1516abffa7aea7972ebaf558c77bcd8999c397606bf66b9cf27f7519bc5198ea
+  metadata.gz: bfda16db0b33649065d21a3df62ae7f3b6962adaa0e57fd11944b5e0edce780f
+  data.tar.gz: 476dd4536d5bae00d3e169d26c30bb98ac3ab24aa82fe4b4b65a47b55cb57bea
 SHA512:
-  metadata.gz: 5778815c08e0d3cda4217a0c0b559ef6ad9e840b7c83760409875a446c9bcfcd9d26ee96caa18c74ef4ba194e9d51e6974e1b32d3ce58daec68fbb2ab510b52c
-  data.tar.gz: '089dd3ea229d309050d63097ce83bc2b4f74a2c2513b1668a716154563b5a9d01e9e9a4ebe4ab384f1c9f9d83a3f7f804ac2dcbbc8681d831817f26a18412934'
+  metadata.gz: 6ffcf4cddf3cfafe432cb53bff0ebda0b0f8af4fc9d113e18fd5540cddc3328fe32d40d47b5ce8922cb32e4e758198e24a804c939e4676aa842991ebe98334e5
+  data.tar.gz: 35f100a37e7fdc727c8bf824726c907100286d41b4738e7aa78fe2d4f9e9fe05bdcdeef296f3898ecbe14193842957132e1bc2ccddcb8ab86448015ff49a9232

data/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to the Mobiscroll Connect Ruby SDK (RubyGems: `mobiscroll-connect`) are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this SDK's major.minor always matches the Connect API's (for example API 1.5.x → SDK 1.5.x): each release bumps only the patch, including releases with breaking changes. Patch numbers are independent per SDK, so this file covers the Ruby SDK only.
+
+## [1.6.0] — 2026-10-08
+
+### Added
+
+- `webhooks.verify_webhook` checks a delivery's Ed25519 signature and timestamp and returns the parsed `WebhookDelivery`, or raises `WebhookVerificationError`. It fetches and caches the public keys from `/.well-known/webhook-keys` and re-fetches them once before rejecting, so key rotations need no action.
+- `webhook_public_key` client option: a pinned key, used only when the keys endpoint cannot be reached.
+- `Mobiscroll::Connect.verify_webhook_signature` for verifying against keys you supply, with no fetching.
+
+## [1.5.1] — 2026-09-22
+
+### Changed
+
+- Updated package metadata. No code or public API changes.
+
+## [1.5.0] — 2026-09-21
+
+### Added
+
+- `webhooks` resource with `subscribe_webhook()` and `unsubscribe_webhook()` for calendar change notifications.
+- `sync_state` and `sync_state_updated_at` on `ConnectedAccount`.
+
+## [1.2.0] — 2026-08-27
+
+### Added
+
+- Granted OAuth scopes are reported on the connection status, and a missing scope now raises `CalendarPermissionError`.
+
+## [1.1.0] — 2026-06-03
+
+### Added
+
+- Optional `lng` parameter on the authorization URL, for Connect's localized consent screens.
+
+## [1.0.2] — 2026-05-26
+
+### Added
+
+- First published release: `auth`, `calendars` and `events` resources over Google Calendar, Microsoft Outlook, Apple Calendar and CalDAV.
+- Automatic token refresh on 401 with an `on_tokens_refreshed` callback.
+- Typed error hierarchy rooted at `Mobiscroll::Connect::Error`.
+- Sinatra reference application under `minimal-app/`.
+
+### Changed
+
+- Minimum supported Ruby raised to 3.2.
+
+[1.5.1]: https://github.com/acidb/mobiscroll-connect-sdks/releases/tag/ruby-v1.5.1
+[1.5.0]: https://github.com/acidb/mobiscroll-connect-sdks/releases/tag/ruby-v1.5.0
+[1.2.0]: https://github.com/acidb/mobiscroll-connect-sdks/releases/tag/ruby-v1.2.0
+[1.1.0]: https://github.com/acidb/mobiscroll-connect-sdks/releases/tag/ruby-v1.1.0
+[1.0.2]: https://github.com/acidb/mobiscroll-connect-sdks/releases/tag/ruby-v1.0.2

data/README.md

@@ -1,6 +1,10 @@
 # Mobiscroll Connect Ruby SDK
 
-Official Ruby client for the [Mobiscroll Connect API](https://connect.mobiscroll.com). Sync calendar events across Google Calendar, Microsoft Outlook, Apple Calendar, and CalDAV.
+Ruby client for [Mobiscroll Connect](https://mobiscroll.com/connect), the calendar connectivity layer for scheduling products — Google Calendar, Microsoft Outlook, Apple Calendar and CalDAV through one API. Backend only — works with your own UI.
+
+[![RubyGems](https://img.shields.io/gem/v/mobiscroll-connect?label=RubyGems)](https://rubygems.org/gems/mobiscroll-connect)
+
+**[RubyGems](https://rubygems.org/gems/mobiscroll-connect)** · **[Documentation](https://mobiscroll.com/docs/connect/ruby-sdk)** · **[Changelog](https://github.com/acidb/mobiscroll-connect-sdks/blob/main/sdks/ruby/CHANGELOG.md)** · **[Source](https://github.com/acidb/mobiscroll-connect-sdks/tree/main/sdks/ruby)**
 
 ## Installation
 
@@ -94,6 +98,8 @@ The SDK automatically refreshes expired access tokens. When a request returns 40
 
 Concurrent 401s share a single in-flight refresh — only one `POST /oauth/token` is ever issued per `Client` instance at a time.
 
+**Running more than one instance.** The single in-flight refresh above is per `Client` instance. The SDK does not coordinate across processes — separate containers, cluster workers or serverless invocations each refresh from the tokens they hold in memory. Connect accepts concurrent refreshes of the same token, but refreshing with a copy that is two or more refreshes out of date revokes the user's authorization. Persist refreshed tokens to storage every instance reads, and call `client.set_credentials(...)` with the current tokens when a process starts a job or handles a request. See [Refreshing from several instances](https://mobiscroll.com/docs/connect/api/oauth#concurrent-refresh).
+
 To persist refreshed tokens (e.g., back to a session or database):
 
 ```ruby
@@ -193,6 +199,40 @@ client.webhooks.unsubscribe_webhook(
 )
 ```
 
+### Verify webhook deliveries
+
+Every delivery to your webhook URL is signed. `verify_webhook` checks the signature and the timestamp, then returns the parsed `WebhookDelivery`, or raises `WebhookVerificationError`. Pass the **raw** request body: a JSON body parser that runs first changes the bytes and every check fails.
+
+```ruby
+post '/webhooks/mobiscroll' do
+  begin
+    delivery = client.webhooks.verify_webhook(request.body.read, request.env)
+  rescue Mobiscroll::Connect::WebhookVerificationError => e
+    # 503 lets Connect retry when the keys could not be loaded; 401 is final.
+    halt(e.reason == 'no_public_keys' ? 503 : 401)
+  end
+  handle_delivery(delivery)
+  status 204
+end
+```
+
+`headers` can be a Hash with any key casing, a Rack env (`HTTP_WEBHOOK_ID` keys), or Rails' `request.headers` (pass `request.raw_post` as the body in Rails).
+
+The public keys are fetched from `https://connect.mobiscroll.com/.well-known/webhook-keys` on the first delivery and cached for the whole process as the endpoint's `Cache-Control` allows. If no signature matches, the keys are fetched again (at most once a minute) before the delivery is rejected, so key rotations need no action on your side.
+
+If your handler cannot make outbound requests, pin the key. `webhook_public_key` is used only when the keys endpoint cannot be reached; it stops working when Mobiscroll retires that key, so you must replace it on every rotation.
+
+```ruby
+client = Mobiscroll::Connect::Client.new(
+  client_id:          ENV['MOBISCROLL_CLIENT_ID'],
+  client_secret:      ENV['MOBISCROLL_CLIENT_SECRET'],
+  redirect_uri:       ENV['MOBISCROLL_REDIRECT_URI'],
+  webhook_public_key: ENV['MOBISCROLL_WEBHOOK_PUBLIC_KEY'] # whpk_...
+)
+```
+
+To check against keys you supply, with no fetching, call `Mobiscroll::Connect.verify_webhook_signature(raw_body, headers, ['whpk_...'])`. It raises `WebhookVerificationError` and returns `nil`. See [Verifying deliveries](https://mobiscroll.com/docs/connect/api/webhooks#verifying-deliveries).
+
 ## Error handling
 
 All errors are subclasses of `Mobiscroll::Connect::Error`:
@@ -225,6 +265,7 @@ end
 | `RateLimitError` | 429 | `retry_after` (seconds) |
 | `ServerError` | 5xx | `status_code` |
 | `NetworkError` | transport | `cause` |
+| `WebhookVerificationError` | — (from `verify_webhook`) | `reason` |
 
 ## Minimal demo app
 

data/lib/mobiscroll/connect/client.rb

@@ -7,14 +7,15 @@ module Mobiscroll
 
       def initialize(client_id:, client_secret:, redirect_uri:,
                      base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT,
-                     on_tokens_refreshed: nil)
+                     on_tokens_refreshed: nil, webhook_public_key: nil)
         @config = Config.new(
           client_id: client_id,
           client_secret: client_secret,
           redirect_uri: redirect_uri,
           base_url: base_url,
           timeout: timeout,
-          on_tokens_refreshed: on_tokens_refreshed
+          on_tokens_refreshed: on_tokens_refreshed,
+          webhook_public_key: webhook_public_key
         )
         @api_client = ApiClient.new(@config)
         @auth = Resources::Auth.new(@config, @api_client)

data/lib/mobiscroll/connect/config.rb

@@ -6,12 +6,14 @@ module Mobiscroll
     DEFAULT_TIMEOUT = 30
 
     class Config
-      attr_reader :client_id, :client_secret, :redirect_uri, :base_url, :timeout
+      # `webhook_public_key` is a pinned `whpk_` key, used by Webhooks#verify_webhook only when
+      # the keys endpoint cannot be reached; it stops verifying once Mobiscroll retires that key.
+      attr_reader :client_id, :client_secret, :redirect_uri, :base_url, :timeout, :webhook_public_key
       attr_accessor :on_tokens_refreshed
 
       def initialize(client_id:, client_secret:, redirect_uri:,
                      base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT,
-                     on_tokens_refreshed: nil)
+                     on_tokens_refreshed: nil, webhook_public_key: nil)
         raise Error, 'client_id is required' if client_id.nil? || client_id.empty?
         raise Error, 'client_secret is required' if client_secret.nil? || client_secret.empty?
         raise Error, 'redirect_uri is required' if redirect_uri.nil? || redirect_uri.empty?
@@ -22,6 +24,7 @@ module Mobiscroll
         @base_url = base_url
         @timeout = timeout
         @on_tokens_refreshed = on_tokens_refreshed
+        @webhook_public_key = webhook_public_key
       end
     end
   end

data/lib/mobiscroll/connect/errors.rb

@@ -78,6 +78,19 @@ module Mobiscroll
       end
     end
 
+    # Raised when a webhook delivery fails verification. Respond with a 4xx and do not process it.
+    #
+    # +reason+ is one of 'missing_headers', 'invalid_timestamp', 'timestamp_out_of_tolerance',
+    # 'no_public_keys', 'no_matching_signature' or 'invalid_payload'.
+    class WebhookVerificationError < Error
+      attr_reader :reason
+
+      def initialize(message = 'Webhook verification failed', reason: nil)
+        super(message, code: 'WEBHOOK_VERIFICATION_ERROR')
+        @reason = reason
+      end
+    end
+
     # Maps an HTTP response (status + body hash + headers) to the matching
     # typed error. Returns nil for 2xx responses.
     def self.map_response_error(status, body, headers)

data/lib/mobiscroll/connect/models.rb

@@ -242,6 +242,52 @@ module Mobiscroll
       end
     end
 
+    # A changed event in a webhook delivery: every CalendarEvent field plus `change_type`
+    # ('created', 'updated' or 'deleted').
+    WebhookEvent = Struct.new(*CalendarEvent.members, :change_type, keyword_init: true) do
+      def self.from_h(hash)
+        return nil if hash.nil?
+
+        new(**CalendarEvent.from_h(hash).to_h, change_type: hash['changeType'] || hash[:changeType])
+      end
+    end
+
+    # `metadata` of a webhook delivery.
+    WebhookDeliveryMetadata = Struct.new(:channel_id, :event_count, :is_initial_sync, keyword_init: true) do
+      def self.from_h(hash)
+        return nil if hash.nil?
+
+        key = 'isInitialSync'
+        new(
+          channel_id: hash['channelId'] || hash[:channelId],
+          event_count: hash['eventCount'] || hash[:eventCount],
+          is_initial_sync: hash.key?(key) ? hash[key] : hash[key.to_sym]
+        )
+      end
+    end
+
+    # A verified webhook delivery, returned by Webhooks#verify_webhook. `change_type` is
+    # 'created', 'updated', 'deleted' or 'mixed'; `timestamp` is the ISO 8601 time Connect
+    # processed the change.
+    WebhookDelivery = Struct.new(
+      :provider, :user_id, :calendar_id, :events, :change_type, :timestamp, :metadata, keyword_init: true
+    ) do
+      def self.from_h(hash)
+        return nil if hash.nil?
+
+        metadata = hash['metadata'] || hash[:metadata]
+        new(
+          provider: hash['provider'] || hash[:provider],
+          user_id: hash['userId'] || hash[:userId],
+          calendar_id: hash['calendarId'] || hash[:calendarId],
+          events: Array(hash['events'] || hash[:events]).filter_map { |e| WebhookEvent.from_h(e) if e.is_a?(Hash) },
+          change_type: hash['changeType'] || hash[:changeType],
+          timestamp: hash['timestamp'] || hash[:timestamp],
+          metadata: metadata.is_a?(Hash) ? WebhookDeliveryMetadata.from_h(metadata) : nil
+        )
+      end
+    end
+
     # Response from Webhooks#unsubscribe_webhook. `success` is true whenever the local
     # mapping was removed, even if the provider-side unsubscribe itself failed — `message`
     # explains what happened in that case.

data/lib/mobiscroll/connect/resources/webhooks.rb

@@ -1,12 +1,16 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'uri'
 
 module Mobiscroll
   module Connect
     module Resources
       class Webhooks
-        def initialize(_config, api_client)
+        RETRYABLE_REASONS = %w[no_matching_signature no_public_keys].freeze
+
+        def initialize(config, api_client)
+          @config = config
           @api_client = api_client
         end
 
@@ -36,6 +40,62 @@ module Mobiscroll
           parsed = @api_client.post('/unsubscribe-webhook', body: JSON.generate(body))
           UnsubscribeWebhookResponse.from_h(parsed)
         end
+
+        # Verifies that a webhook delivery came from Mobiscroll Connect, and parses it.
+        #
+        # Fetches the public keys from `/.well-known/webhook-keys` on first use and caches them for
+        # the whole process, refreshing them as the endpoint's `Cache-Control` allows. When no
+        # signature matches, it re-fetches the keys once (at most once a minute) before rejecting,
+        # so a key rotation never rejects genuine deliveries. `webhook_public_key` from the config
+        # is used only when the endpoint cannot be reached.
+        #
+        # `payload` is the raw request body String, exactly as received; not a parsed Hash.
+        # `headers` is a Hash (any key casing) or a Rack env / Rails `request.headers`.
+        #
+        # Returns a WebhookDelivery. Raises WebhookVerificationError when the delivery is not
+        # genuine; respond with a 4xx.
+        #
+        #   post '/webhooks/mobiscroll' do
+        #     delivery = client.webhooks.verify_webhook(request.body.read, request.env)
+        #     handle_delivery(delivery)
+        #     status 204
+        #   rescue Mobiscroll::Connect::WebhookVerificationError
+        #     halt 401
+        #   end
+        def verify_webhook(payload, headers)
+          store = WebhookKeyStore.for_url(URI.join(@config.base_url, WEBHOOK_KEYS_PATH).to_s)
+
+          begin
+            Connect.verify_webhook_signature(payload, headers, keys_or_pinned(store.keys))
+          rescue WebhookVerificationError => e
+            raise unless RETRYABLE_REASONS.include?(e.reason) && store.can_refetch?
+
+            store.refresh
+            Connect.verify_webhook_signature(payload, headers, keys_or_pinned(store.keys))
+          end
+
+          parse_delivery(payload)
+        end
+
+        private
+
+        # The pinned key is never merged with fetched keys: after an emergency rotation a pinned
+        # retired key must stop verifying.
+        def keys_or_pinned(keys)
+          pinned = @config.webhook_public_key
+          keys.empty? && pinned && !pinned.empty? ? [pinned] : keys
+        end
+
+        def parse_delivery(payload)
+          parsed = begin
+            JSON.parse(payload.dup.force_encoding(Encoding::UTF_8))
+          rescue JSON::ParserError, EncodingError
+            nil
+          end
+          return WebhookDelivery.from_h(parsed) if parsed.is_a?(Hash)
+
+          raise WebhookVerificationError.new('Webhook payload is not a JSON object', reason: 'invalid_payload')
+        end
       end
     end
   end

data/lib/mobiscroll/connect/version.rb

@@ -2,6 +2,6 @@
 
 module Mobiscroll
   module Connect
-    VERSION = '1.5.0'
+    VERSION = '1.6.0'
   end
 end

data/lib/mobiscroll/connect/webhook_verification.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'faraday'
+require 'json'
+require 'openssl'
+
+module Mobiscroll
+  module Connect
+    WEBHOOK_TOLERANCE_SECONDS = 300
+    WEBHOOK_KEYS_PATH = '/.well-known/webhook-keys'
+
+    # Verifies the Standard Webhooks `v1a` (Ed25519) signature of a Mobiscroll Connect delivery
+    # against the given public keys, without fetching anything.
+    #
+    # Use it with a pinned key in handlers that cannot make outbound requests. Otherwise prefer
+    # `client.webhooks.verify_webhook`, which fetches and refreshes the keys for you.
+    #
+    # `payload` is the raw request body String, exactly as received. `headers` is a Hash (any
+    # key casing, Array values take the first) or a Rack env / Rails `request.headers`, where
+    # `HTTP_WEBHOOK_ID`-style keys are matched too. `public_keys` are `whpk_` keys; the delivery
+    # is genuine if any signature verifies against any key. `now` is the current Unix time in
+    # seconds, defaulting to the system clock.
+    #
+    # Returns nil. Raises WebhookVerificationError when the delivery is not genuine or cannot
+    # be checked.
+    #
+    #   Mobiscroll::Connect.verify_webhook_signature(
+    #     request.body.read, request.env, [ENV.fetch('MOBISCROLL_WEBHOOK_PUBLIC_KEY')]
+    #   )
+    def self.verify_webhook_signature(payload, headers, public_keys,
+                                      tolerance_seconds: WEBHOOK_TOLERANCE_SECONDS, now: nil)
+      WebhookSignature.verify(payload, headers, public_keys, tolerance_seconds: tolerance_seconds, now: now)
+      nil
+    end
+
+    # @api private
+    module WebhookSignature
+      PUBLIC_KEY_PREFIX = 'whpk_'
+      SIGNATURE_VERSION = 'v1a'
+      # DER SubjectPublicKeyInfo header for an Ed25519 key; `OpenSSL::PKey.new_raw_public_key`
+      # needs openssl gem 3.2+, which Ruby 3.2 does not bundle.
+      ED25519_SPKI_PREFIX = ['302a300506032b6570032100'].pack('H*').freeze
+
+      module_function
+
+      def verify(payload, headers, public_keys, tolerance_seconds:, now:)
+        unless payload.is_a?(String)
+          raise WebhookVerificationError.new(
+            'Pass the raw request body as a String, not a parsed object', reason: 'invalid_payload'
+          )
+        end
+
+        id = read_header(headers, 'webhook-id')
+        timestamp = read_header(headers, 'webhook-timestamp')
+        signature_header = read_header(headers, 'webhook-signature')
+        if [id, timestamp, signature_header].any? { |value| value.nil? || value.empty? }
+          raise WebhookVerificationError.new(
+            'Missing webhook-id, webhook-timestamp or webhook-signature header', reason: 'missing_headers'
+          )
+        end
+
+        check_timestamp(timestamp, tolerance_seconds, now || Time.now.to_i)
+
+        keys = Array(public_keys).filter_map { |key| parse_public_key(key) }
+        if keys.empty?
+          raise WebhookVerificationError.new('No valid webhook public keys available', reason: 'no_public_keys')
+        end
+
+        signed_content = "#{id}.#{timestamp}.".b << payload.b
+        return if signature_header.split(/ /).any? { |entry| entry_matches?(entry, signed_content, keys) }
+
+        raise WebhookVerificationError.new('No webhook signature matched', reason: 'no_matching_signature')
+      end
+
+      def check_timestamp(timestamp, tolerance_seconds, now)
+        unless timestamp.match?(/\A\d+\z/)
+          raise WebhookVerificationError.new('Invalid webhook-timestamp header', reason: 'invalid_timestamp')
+        end
+        return if (now - timestamp.to_i).abs <= tolerance_seconds
+
+        raise WebhookVerificationError.new(
+          'Webhook timestamp is outside the allowed tolerance', reason: 'timestamp_out_of_tolerance'
+        )
+      end
+
+      def read_header(headers, name)
+        return nil unless headers.respond_to?(:each)
+
+        rack_name = "HTTP_#{name.upcase.tr('-', '_')}"
+        headers.each do |key, value|
+          next unless key.to_s.casecmp?(name) || key.to_s.casecmp?(rack_name)
+
+          value = value.first if value.is_a?(Array)
+          return value&.to_s&.b
+        end
+        nil
+      end
+
+      def parse_public_key(value)
+        return nil unless value.is_a?(String)
+
+        raw = Base64.decode64(value.strip.delete_prefix(PUBLIC_KEY_PREFIX))
+        return nil unless raw.bytesize == 32
+
+        OpenSSL::PKey.read(ED25519_SPKI_PREFIX + raw)
+      rescue OpenSSL::PKey::PKeyError
+        nil
+      end
+
+      def entry_matches?(entry, signed_content, keys)
+        version, separator, encoded = entry.partition(',')
+        return false if separator.empty? || version != SIGNATURE_VERSION
+
+        signature = Base64.decode64(encoded)
+        return false unless signature.bytesize == 64
+
+        keys.any? do |key|
+          key.verify(nil, signature, signed_content)
+        rescue OpenSSL::PKey::PKeyError
+          false
+        end
+      end
+    end
+    private_constant :WebhookSignature
+
+    # Process-wide cache of the keys published at one keys URL, shared by every client instance.
+    # Follows the endpoint's `Cache-Control`, re-fetches at most once a minute, and keeps the last
+    # good keys when a fetch fails. Concurrent callers share one in-flight fetch.
+    #
+    # @api private
+    class WebhookKeyStore
+      DEFAULT_MAX_AGE = 60 * 60
+      MAX_MAX_AGE = 24 * 60 * 60
+      MIN_REFETCH_INTERVAL = 60
+      FETCH_TIMEOUT = 10
+
+      @stores = {}
+      @stores_lock = Mutex.new
+
+      class << self
+        def for_url(url)
+          @stores_lock.synchronize { @stores[url] ||= new(url) }
+        end
+
+        # Clears every cached key set; for tests.
+        def reset!
+          @stores_lock.synchronize { @stores.clear }
+        end
+      end
+
+      def initialize(url)
+        @url = url
+        @keys = [].freeze
+        @fetched_at = nil
+        @last_attempt_at = nil
+        @max_age = DEFAULT_MAX_AGE
+        @in_flight = false
+        @lock = Mutex.new
+        @cond = ConditionVariable.new
+      end
+
+      # The current keys, fetching them first when they are missing or stale and a fetch is allowed.
+      def keys
+        fetch_if { |now| stale?(now) && can_refetch_at?(now) }
+        @lock.synchronize { @keys }
+      end
+
+      def can_refetch?
+        @lock.synchronize { can_refetch_at?(Time.now.to_f) }
+      end
+
+      # Fetches the keys unless a fetch was attempted in the last minute; joins one in flight.
+      def refresh
+        fetch_if { |now| can_refetch_at?(now) }
+      end
+
+      private
+
+      def stale?(now)
+        @fetched_at.nil? || now - @fetched_at > @max_age
+      end
+
+      def can_refetch_at?(now)
+        @last_attempt_at.nil? || now - @last_attempt_at >= MIN_REFETCH_INTERVAL
+      end
+
+      # Starts a fetch when the block allows it, or waits for the one already in flight; the
+      # decision and the in-flight flag are taken under one lock so callers never fetch twice.
+      def fetch_if
+        @lock.synchronize do
+          if @in_flight
+            @cond.wait(@lock) while @in_flight
+            return
+          end
+          now = Time.now.to_f
+          return unless yield(now)
+
+          @in_flight = true
+          @last_attempt_at = now
+        end
+
+        result = nil
+        begin
+          result = fetch_keys
+        ensure
+          @lock.synchronize do
+            if result
+              @keys, @max_age = result
+              @fetched_at = Time.now.to_f
+            end
+            @in_flight = false
+            @cond.broadcast
+          end
+        end
+      end
+
+      # Returns [keys, max_age], or nil when the fetch fails or yields no usable key. Uses a plain
+      # connection: the keys endpoint is public and must never go through the token-refresh path.
+      def fetch_keys
+        response = Faraday.new(request: { timeout: FETCH_TIMEOUT, open_timeout: FETCH_TIMEOUT }).get(@url) do |req|
+          req.headers['Accept'] = 'application/json'
+        end
+        return nil unless response.success?
+
+        parsed = JSON.parse(response.body.to_s)
+        keys = Array(parsed.is_a?(Hash) ? parsed['keys'] : nil).filter_map { |entry| usable_key(entry) }
+        keys.empty? ? nil : [keys.freeze, parse_max_age(response.headers['cache-control'])]
+      rescue StandardError
+        nil
+      end
+
+      def usable_key(entry)
+        return nil unless entry.is_a?(Hash)
+
+        key = entry['key']
+        alg = entry['alg'].to_s
+        return nil unless key.is_a?(String) && key.start_with?(WebhookSignature::PUBLIC_KEY_PREFIX)
+        return nil unless alg.empty? || alg.casecmp?('ed25519')
+
+        key
+      end
+
+      def parse_max_age(cache_control)
+        match = /max-age=(\d+)/i.match(cache_control.to_s)
+        match ? [match[1].to_i, MAX_MAX_AGE].min : DEFAULT_MAX_AGE
+      end
+    end
+  end
+end

data/lib/mobiscroll/connect.rb

@@ -6,6 +6,7 @@ require_relative 'connect/provider'
 require_relative 'connect/config'
 require_relative 'connect/models'
 require_relative 'connect/api_client'
+require_relative 'connect/webhook_verification'
 require_relative 'connect/resources/auth'
 require_relative 'connect/resources/calendars'
 require_relative 'connect/resources/events'

data/mobiscroll-connect.gemspec

@@ -8,10 +8,13 @@ Gem::Specification.new do |spec|
   spec.authors     = ['Mobiscroll']
   spec.email       = ['support@mobiscroll.com']
 
-  spec.summary     = 'Official Ruby SDK for the Mobiscroll Connect API.'
-  spec.description = 'Ruby client for the Mobiscroll Connect API. Unified ' \
-                     'OAuth, calendars, and events across Google Calendar, ' \
-                     'Microsoft Outlook, Apple Calendar, and CalDAV.'
+  spec.summary     = 'Ruby client for Mobiscroll Connect — Google Calendar, ' \
+                     'Microsoft Outlook, Apple Calendar and CalDAV through one API.'
+  spec.description = 'Ruby client for Mobiscroll Connect, the calendar ' \
+                     'connectivity layer for scheduling products. Google ' \
+                     'Calendar, Microsoft Outlook, Apple Calendar and CalDAV ' \
+                     'through one API, with OAuth 2.0 and webhooks. Backend ' \
+                     'only — works with your own UI.'
   spec.homepage    = 'https://mobiscroll.com/connect'
   spec.license     = 'MIT'
 
@@ -19,7 +22,8 @@ Gem::Specification.new do |spec|
 
   spec.metadata = {
     'homepage_uri' => spec.homepage,
-    'source_code_uri' => 'https://github.com/acidb/mobiscroll-connect-sdks',
+    'source_code_uri' => 'https://github.com/acidb/mobiscroll-connect-sdks/tree/main/sdks/ruby',
+    'documentation_uri' => 'https://mobiscroll.com/docs/connect/ruby-sdk',
     'bug_tracker_uri' => 'https://github.com/acidb/mobiscroll-connect-sdks/issues',
     'changelog_uri' => 'https://github.com/acidb/mobiscroll-connect-sdks/blob/main/sdks/ruby/CHANGELOG.md',
     'rubygems_mfa_required' => 'true'
@@ -28,6 +32,7 @@ Gem::Specification.new do |spec|
   spec.files = Dir[
     'lib/**/*.rb',
     'README.md',
+    'CHANGELOG.md',
     'LICENSE',
     'mobiscroll-connect.gemspec'
   ]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mobiscroll-connect
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Mobiscroll
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-22 00:00:00.000000000 Z
+date: 2026-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -80,14 +80,17 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.23'
-description: Ruby client for the Mobiscroll Connect API. Unified OAuth, calendars,
-  and events across Google Calendar, Microsoft Outlook, Apple Calendar, and CalDAV.
+description: Ruby client for Mobiscroll Connect, the calendar connectivity layer for
+  scheduling products. Google Calendar, Microsoft Outlook, Apple Calendar and CalDAV
+  through one API, with OAuth 2.0 and webhooks. Backend only — works with your own
+  UI.
 email:
 - support@mobiscroll.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - lib/mobiscroll-connect.rb
@@ -103,13 +106,15 @@ files:
 - lib/mobiscroll/connect/resources/events.rb
 - lib/mobiscroll/connect/resources/webhooks.rb
 - lib/mobiscroll/connect/version.rb
+- lib/mobiscroll/connect/webhook_verification.rb
 - mobiscroll-connect.gemspec
 homepage: https://mobiscroll.com/connect
 licenses:
 - MIT
 metadata:
   homepage_uri: https://mobiscroll.com/connect
-  source_code_uri: https://github.com/acidb/mobiscroll-connect-sdks
+  source_code_uri: https://github.com/acidb/mobiscroll-connect-sdks/tree/main/sdks/ruby
+  documentation_uri: https://mobiscroll.com/docs/connect/ruby-sdk
   bug_tracker_uri: https://github.com/acidb/mobiscroll-connect-sdks/issues
   changelog_uri: https://github.com/acidb/mobiscroll-connect-sdks/blob/main/sdks/ruby/CHANGELOG.md
   rubygems_mfa_required: 'true'
@@ -131,5 +136,6 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Official Ruby SDK for the Mobiscroll Connect API.
+summary: Ruby client for Mobiscroll Connect — Google Calendar, Microsoft Outlook,
+  Apple Calendar and CalDAV through one API.
 test_files: []