assinafy 1.5.0

data/lib/assinafy/support/webhook_verifier.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'json'
+
+module Assinafy
+  module Support
+    # Defensive helper for verifying webhook deliveries when your gateway or
+    # proxy signs the body with an HMAC-SHA256 secret.
+    #
+    # The Assinafy v1 API itself does not currently document a
+    # request-signing scheme for webhook deliveries, so this class is opt-in:
+    # construct it with a secret only if you have one configured in front
+    # of your webhook receiver (e.g. via API Gateway / Cloudflare).
+    # HMAC verifies authenticity, not freshness; the receiver must separately
+    # reject replayed event IDs or enforce its gateway's timestamp policy.
+    #
+    # @example Verify and dispatch a webhook
+    #   verifier = Assinafy::Support::WebhookVerifier.new(ENV['WEBHOOK_SECRET'])
+    #   raw_body = request.body.read
+    #   # NOTE: the header below is one YOUR gateway injects (e.g. Cloudflare /
+    #   # API Gateway). Assinafy v1 does not send a signature header itself.
+    #   if verifier.verify(raw_body, request.headers['X-Webhook-Signature'])
+    #     event = verifier.extract_event(raw_body)
+    #     verifier.event_type(event)    # => "assignment_created"
+    #     verifier.event_payload(event) # => { "user_name" => "John", ... } (or nil)
+    #     verifier.event_object(event)  # => { "id" => "doc2", "type" => "Document", ... }
+    #     verifier.event_subject(event) # => { "id" => "...", "type" => "User", ... }
+    #   end
+    class WebhookVerifier
+      # @param webhook_secret [String, nil] shared secret. When nil/empty,
+      #   {#verify} always returns false (safe-by-default).
+      def initialize(webhook_secret = nil)
+        @webhook_secret = webhook_secret
+      end
+
+      # Constant-time compare the provided signature to the expected
+      # HMAC-SHA256 of the raw payload.
+      #
+      # @param payload   [String]  raw HTTP body
+      # @param signature [String]  hex-encoded signature header value
+      # @return [Boolean]
+      def verify(payload, signature)
+        return false unless @webhook_secret && !@webhook_secret.empty?
+        return false unless signature && !signature.to_s.strip.empty?
+
+        body     = payload.is_a?(String) ? payload : payload.to_s
+        expected = OpenSSL::HMAC.hexdigest('SHA256', @webhook_secret, body)
+        provided = signature.to_s.strip
+
+        OpenSSL.fixed_length_secure_compare(expected, provided)
+      rescue StandardError
+        false
+      end
+
+      # Parse a JSON webhook body into a Hash, returning nil on malformed or
+      # non-object payloads.
+      #
+      # @param payload [String]
+      # @return [Hash, nil]
+      def extract_event(payload)
+        text   = payload.is_a?(String) ? payload : payload.to_s
+        parsed = JSON.parse(text)
+        parsed.is_a?(Hash) ? parsed : nil
+      rescue JSON::ParserError
+        nil
+      end
+
+      # Pull the event-type code from a parsed event Hash. The canonical key in
+      # the Assinafy v1 delivery envelope is `event` (e.g. `assignment_created`).
+      #
+      # @param event [Hash, nil]
+      # @return [String, nil]
+      # @example
+      #   verifier.event_type({ 'event' => 'document_ready' }) # => "document_ready"
+      def event_type(event)
+        return nil unless event.is_a?(Hash)
+
+        event['event']
+      end
+
+      # The event-specific data snapshot (the documented top-level `payload`).
+      # May be `nil` for events that carry no extra params (e.g.
+      # `document_uploaded`).
+      #
+      # @param event [Hash, nil]
+      # @return [Hash, nil]
+      def event_payload(event)
+        return nil unless event.is_a?(Hash)
+
+        event['payload']
+      end
+
+      # The entity the event acted on (the documented top-level `object`),
+      # e.g. the Document. Includes a `type` discriminator.
+      #
+      # @param event [Hash, nil]
+      # @return [Hash]
+      def event_object(event)
+        return {} unless event.is_a?(Hash)
+
+        event['object'] || {}
+      end
+
+      # The actor that triggered the event (the documented top-level `subject`),
+      # e.g. the User. Includes a `type` discriminator.
+      #
+      # @param event [Hash, nil]
+      # @return [Hash]
+      def event_subject(event)
+        return {} unless event.is_a?(Hash)
+
+        event['subject'] || {}
+      end
+
+      # @deprecated Prefer {#event_payload} (event params) and {#event_object}
+      #   (acted-on entity). The Assinafy envelope has no top-level `data` key;
+      #   this returns `payload` and falls back to `object` for convenience.
+      #
+      # @param event [Hash, nil]
+      # @return [Hash]
+      def event_data(event)
+        return {} unless event.is_a?(Hash)
+
+        event['payload'] || event['object'] || {}
+      end
+    end
+  end
+end

data/lib/assinafy/utils.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Assinafy
+  # Small, stateless helpers shared across resources. Intentionally private
+  # by convention — callers should reach for these via the resource methods,
+  # not directly.
+  module Utils
+    MAX_NORMALIZATION_DEPTH = 100
+
+    class << self
+      # Unwrap an Assinafy envelope — a Hash with a numeric `status` and an
+      # optional `data` key. Returns `data` (or nil) for 2xx, raises {ApiError}
+      # otherwise, and passes through non-envelope bodies.
+      #
+      # @param body [Hash, Object]
+      # @return [Object]
+      def handle_assinafy_response(body)
+        return body unless body.is_a?(Hash)
+        return body unless body.key?('status')
+
+        status = Integer(body['status'], exception: false)
+        return body unless status
+
+        if status >= 200 && status < 300
+          body['data'] if body.key?('data')
+        else
+          raise ApiError.from_response(status, body)
+        end
+      end
+
+      # Drop nil values (but keep `false`).
+      #
+      # @param hash [Hash, nil]
+      # @return [Hash]
+      def clean_params(hash)
+        return {} if hash.nil?
+        raise ValidationError.new('Parameters must be a Hash') unless hash.is_a?(Hash)
+
+        hash.each_with_object({}) do |(key, value), result|
+          result[key] = value unless value.nil?
+        end
+      end
+
+      # Build a query-string Hash, translating the Ruby-friendly snake_case
+      # aliases in {query_key_map} to the hyphenated forms documented in the
+      # Assinafy API (e.g. `per_page` → `per-page`).
+      #
+      # @param hash [Hash, nil]
+      # @return [Hash{String=>Object}]
+      def query_params(hash)
+        normalize_keys(clean_params(hash), query_key_map)
+      end
+
+      # Build a body Hash, translating documented hyphenated body keys
+      # (`signer-access-code`, `verification-code`) while passing everything
+      # else through as-is.
+      #
+      # @param hash [Hash, nil]
+      # @return [Hash{String=>Object}]
+      def body_params(hash)
+        normalize_keys(clean_params(hash), body_key_map)
+      end
+
+      private
+
+      def normalize_keys(hash, key_map, seen = {}.compare_by_identity, depth = 0)
+        if depth > MAX_NORMALIZATION_DEPTH || seen.key?(hash)
+          raise ValidationError.new('Parameters are nested too deeply or contain a cycle')
+        end
+
+        seen[hash] = true
+        hash.each_with_object({}) do |(key, value), result|
+          result[normalize_key(key, key_map)] = normalize_value(value, key_map, seen, depth)
+        end
+      ensure
+        seen.delete(hash)
+      end
+
+      def normalize_value(value, key_map, seen, depth)
+        case value
+        when Hash
+          normalize_keys(value, key_map, seen, depth + 1)
+        when Array
+          normalize_array(value, key_map, seen, depth + 1)
+        else
+          value
+        end
+      end
+
+      def normalize_array(array, key_map, seen, depth)
+        if depth > MAX_NORMALIZATION_DEPTH || seen.key?(array)
+          raise ValidationError.new('Parameters are nested too deeply or contain a cycle')
+        end
+
+        seen[array] = true
+        array.map { |item| normalize_value(item, key_map, seen, depth) }
+      ensure
+        seen.delete(array)
+      end
+
+      def normalize_key(key, key_map)
+        raw = key.to_s
+        key_map.fetch(raw, raw)
+      end
+
+      def query_key_map
+        {
+          'access_token'       => 'access-token',
+          'per_page'           => 'per-page',
+          'signer_access_code' => 'signer-access-code'
+        }
+      end
+
+      def body_key_map
+        {
+          'signer_access_code' => 'signer-access-code',
+          'verification_code'  => 'verification-code'
+        }
+      end
+    end
+  end
+end

data/lib/assinafy/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Assinafy
+  VERSION = '1.5.0'
+end

data/lib/assinafy.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/multipart'
+require 'stringio'
+
+require_relative 'assinafy/version'
+require_relative 'assinafy/errors'
+require_relative 'assinafy/null_logger'
+require_relative 'assinafy/configuration'
+require_relative 'assinafy/utils'
+require_relative 'assinafy/resources/base_resource'
+require_relative 'assinafy/resources/auth_resource'
+require_relative 'assinafy/resources/account_resource'
+require_relative 'assinafy/resources/user_resource'
+require_relative 'assinafy/resources/document_resource'
+require_relative 'assinafy/resources/signer_resource'
+require_relative 'assinafy/resources/signer_document_resource'
+require_relative 'assinafy/resources/assignment_resource'
+require_relative 'assinafy/resources/webhook_resource'
+require_relative 'assinafy/resources/template_resource'
+require_relative 'assinafy/resources/field_resource'
+require_relative 'assinafy/resources/tag_resource'
+require_relative 'assinafy/support/webhook_verifier'
+require_relative 'assinafy/client'

metadata

@@ -0,0 +1,195 @@
+--- !ruby/object:Gem::Specification
+name: assinafy
+version: !ruby/object:Gem::Version
+  version: 1.5.0
+platform: ruby
+authors:
+- Assinafy SDK Contributors
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.14.3
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.14.3
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-multipart
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: bundler-audit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.86'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.86'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Ruby SDK for Assinafy. Covers the documented authentication, account,
+  user, document, signer, assignment, webhook, template, tag, and field APIs, plus
+  the high-level upload_and_request_signatures helper.
+email:
+- sdk@assinafy.com.br
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/assinafy.rb
+- lib/assinafy/client.rb
+- lib/assinafy/configuration.rb
+- lib/assinafy/errors.rb
+- lib/assinafy/null_logger.rb
+- lib/assinafy/resources/account_resource.rb
+- lib/assinafy/resources/assignment_resource.rb
+- lib/assinafy/resources/auth_resource.rb
+- lib/assinafy/resources/base_resource.rb
+- lib/assinafy/resources/document_resource.rb
+- lib/assinafy/resources/field_resource.rb
+- lib/assinafy/resources/signer_document_resource.rb
+- lib/assinafy/resources/signer_resource.rb
+- lib/assinafy/resources/tag_resource.rb
+- lib/assinafy/resources/template_resource.rb
+- lib/assinafy/resources/user_resource.rb
+- lib/assinafy/resources/webhook_resource.rb
+- lib/assinafy/support/webhook_verifier.rb
+- lib/assinafy/utils.rb
+- lib/assinafy/version.rb
+homepage: https://github.com/assinafy/ruby-sdk
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/assinafy/ruby-sdk
+  bug_tracker_uri: https://github.com/assinafy/ruby-sdk/issues
+  changelog_uri: https://github.com/assinafy/ruby-sdk/blob/main/CHANGELOG.md
+  documentation_uri: https://api.assinafy.com.br/v1/docs
+  github_repo: ssh://github.com/assinafy/ruby-sdk
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Ruby SDK for the Assinafy digital signature API
+test_files: []