lex-webhook 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9579600380a6b56342f0243c7ed666aae7cd77ede4a90ac780a0d46af4b772c0
+  data.tar.gz: 885f7bf1a903e40cbd07bb033e58de3d8ed6128371cf1eec0fb920e811cfdb4c
+SHA512:
+  metadata.gz: 20bf93dd85ec020cf81c6d8b1859585df3dd3f30fb1ea06a2ca80bcdb60402627061ddfa2b92d756e6e060bd76436867f1b1afb87fc0dc3e458da3fdb2ad3ce5
+  data.tar.gz: 277c023cee59b78e4457aa42b74a7c514b2ab0ac0e2015df53571a2c22ed376141dd5241705bad0d6672494ffdd4bc5d181e79cb0a8fc93003d4e2fd6dd842f3

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [origin]
+  pull_request:
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  release:
+    needs: ci
+    if: github.event_name == 'push' && github.ref == 'refs/heads/origin'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+Gemfile.lock
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,53 @@
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+  SuggestExtensions: false
+
+Layout/LineLength:
+  Max: 160
+
+Layout/SpaceAroundEqualsInParameterDefault:
+  EnforcedStyle: space
+
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
+Metrics/MethodLength:
+  Max: 50
+
+Metrics/ClassLength:
+  Max: 1500
+
+Metrics/ModuleLength:
+  Max: 1500
+
+Metrics/BlockLength:
+  Max: 40
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/AbcSize:
+  Max: 60
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/PerceivedComplexity:
+  Max: 17
+
+Style/Documentation:
+  Enabled: false
+
+Style/SymbolArray:
+  Enabled: true
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Naming/FileName:
+  Enabled: false
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## [0.1.0] - 2026-03-21
+
+### Added
+- Initial release
+- `Helpers::Signature` with HMAC compute, verify, and constant-time secure_compare
+- `Runners::Receive` for webhook ingestion with optional signature verification and JSON body parsing
+- `Runners::Verify` for explicit signature validation and computation
+- `Runners::Endpoints` for in-memory endpoint registry (list, register, remove)
+- Standalone `Client` class including all runner modules

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/README.md

@@ -0,0 +1,47 @@
+# lex-webhook
+
+Generic webhook receiving and HMAC signature verification for LegionIO.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'lex-webhook'
+```
+
+## Usage
+
+### Standalone client
+
+```ruby
+client = Legion::Extensions::Webhook::Client.new
+
+# Receive a webhook (with optional HMAC verification)
+result = client.receive(
+  path:    '/hooks/github',
+  headers: { 'x-hub-signature-256' => 'sha256=abc123...' },
+  body:    '{"action":"push"}',
+  method:  'POST',
+  secret:  'my-secret'
+)
+# => { received: true, path: '/hooks/github', payload: { action: 'push' }, verified: true }
+
+# Verify a signature
+result = client.verify(secret: 'my-secret', signature: 'sha256=abc123...', payload: '{"action":"push"}')
+# => { valid: true, algorithm: 'sha256' }
+
+# Compute a signature
+result = client.compute_signature(secret: 'my-secret', payload: '{"action":"push"}')
+# => { signature: 'abc123...' }
+
+# Endpoint registry
+client.register_endpoint(path: '/hooks/github', secret: 'secret1', description: 'GitHub events')
+client.list_endpoints
+# => { endpoints: [{ path: '/hooks/github', secret: 'secret1', description: 'GitHub events' }] }
+client.remove_endpoint(path: '/hooks/github')
+```
+
+## License
+
+MIT

data/lex-webhook.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'legion/extensions/webhook/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-webhook'
+  spec.version       = Legion::Extensions::Webhook::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'Legion::Extensions::Webhook'
+  spec.description   = 'Generic webhook receiving and HMAC signature verification for LegionIO'
+  spec.homepage      = 'https://github.com/LegionIO/lex-webhook'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']        = spec.homepage
+  spec.metadata['source_code_uri']     = 'https://github.com/LegionIO/lex-webhook'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-webhook/blob/main/CHANGELOG.md'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-webhook'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-webhook/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'rubocop-rspec'
+end

data/lib/legion/extensions/webhook/client.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/webhook/runners/receive'
+require 'legion/extensions/webhook/runners/verify'
+require 'legion/extensions/webhook/runners/endpoints'
+
+module Legion
+  module Extensions
+    module Webhook
+      class Client
+        include Runners::Receive
+        include Runners::Verify
+        include Runners::Endpoints
+
+        def initialize(**opts)
+          @opts = opts
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/webhook/helpers/client.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Webhook
+      module Helpers
+        module Client
+          module_function
+
+          def settings
+            return Legion::Settings[:webhook] if defined?(Legion::Settings)
+
+            {}
+          end
+
+          def endpoints_store
+            @endpoints_store ||= []
+          end
+
+          def reset_endpoints!
+            @endpoints_store = []
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/webhook/helpers/signature.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module Legion
+  module Extensions
+    module Webhook
+      module Helpers
+        module Signature
+          module_function
+
+          def verify(secret:, signature:, payload:, algorithm: 'sha256') # rubocop:disable Naming/PredicateMethod
+            computed = compute(secret: secret, payload: payload, algorithm: algorithm)
+            bytes_match?(computed, signature)
+          end
+
+          def compute(secret:, payload:, algorithm: 'sha256')
+            OpenSSL::HMAC.hexdigest(algorithm, secret, payload)
+          end
+
+          def bytes_match?(lhs, rhs)
+            return false if lhs.nil? || rhs.nil?
+
+            lhs_clean = lhs.sub(/\A\w+=/, '')
+            rhs_clean = rhs.sub(/\A\w+=/, '')
+            return false if lhs_clean.bytesize != rhs_clean.bytesize
+
+            lhs_clean.bytes.zip(rhs_clean.bytes).reduce(0) { |acc, (x, y)| acc | (x ^ y) }.zero?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/webhook/runners/endpoints.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Webhook
+      module Runners
+        module Endpoints
+          def list_endpoints(**)
+            { endpoints: endpoint_registry.dup }
+          end
+
+          def register_endpoint(path:, secret: nil, description: nil, **)
+            existing = endpoint_registry.find { |e| e[:path] == path }
+            if existing
+              existing[:secret]      = secret
+              existing[:description] = description
+              return { registered: false, updated: true, path: path }
+            end
+
+            entry = { path: path, secret: secret, description: description }.compact
+            endpoint_registry << entry
+            { registered: true, updated: false, path: path }
+          end
+
+          def remove_endpoint(path:, **)
+            before = endpoint_registry.size
+            endpoint_registry.reject! { |e| e[:path] == path }
+            removed = endpoint_registry.size < before
+            { removed: removed, path: path }
+          end
+
+          private
+
+          def endpoint_registry
+            @endpoint_registry ||= []
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/webhook/runners/receive.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'legion/extensions/webhook/helpers/signature'
+
+module Legion
+  module Extensions
+    module Webhook
+      module Runners
+        module Receive
+          def receive(path:, **opts)
+            headers = opts.fetch(:headers, {})
+            body    = opts.fetch(:body, '')
+            method  = opts.fetch(:method, 'POST')
+            secret  = opts[:secret]
+
+            verified = verify_signature(headers: headers, body: body, secret: secret)
+            payload  = parse_body(headers: headers, body: body)
+
+            { received: true, path: path, method: method, payload: payload, verified: verified }
+          end
+
+          private
+
+          def verify_signature(headers:, body:, secret:)
+            return false if secret.nil?
+
+            sig_header = find_signature_header(headers)
+            return false if sig_header.nil?
+
+            Helpers::Signature.verify(secret: secret, signature: sig_header, payload: body)
+          end
+
+          def find_signature_header(headers)
+            normalized = headers.transform_keys { |key| key.to_s.downcase }
+            normalized['x-hub-signature-256'] ||
+              normalized['x-hub-signature'] ||
+              normalized['x-signature'] ||
+              normalized['x-webhook-signature']
+          end
+
+          def parse_body(headers:, body:)
+            return body if body.nil? || body.empty?
+
+            content_type = headers.transform_keys { |key| key.to_s.downcase }['content-type'].to_s
+            return ::JSON.parse(body, symbolize_names: true) if content_type.include?('json')
+
+            body
+          rescue ::JSON::ParserError
+            body
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/webhook/runners/verify.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/webhook/helpers/signature'
+
+module Legion
+  module Extensions
+    module Webhook
+      module Runners
+        module Verify
+          def verify(secret:, signature:, payload:, algorithm: 'sha256', **)
+            valid = Helpers::Signature.verify(
+              secret:    secret,
+              signature: signature,
+              payload:   payload,
+              algorithm: algorithm
+            )
+            { valid: valid, algorithm: algorithm }
+          end
+
+          def compute_signature(secret:, payload:, algorithm: 'sha256', **)
+            sig = Helpers::Signature.compute(secret: secret, payload: payload, algorithm: algorithm)
+            { signature: sig }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/webhook/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Webhook
+      VERSION = '0.1.1'
+    end
+  end
+end

data/lib/legion/extensions/webhook.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/webhook/version'
+require 'legion/extensions/webhook/helpers/signature'
+require 'legion/extensions/webhook/helpers/client'
+require 'legion/extensions/webhook/runners/receive'
+require 'legion/extensions/webhook/runners/verify'
+require 'legion/extensions/webhook/runners/endpoints'
+require 'legion/extensions/webhook/client'
+
+module Legion
+  module Extensions
+    module Webhook
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined?(:Core)
+    end
+  end
+end

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: lex-webhook
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Generic webhook receiving and HMAC signature verification for LegionIO
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- Gemfile
+- README.md
+- lex-webhook.gemspec
+- lib/legion/extensions/webhook.rb
+- lib/legion/extensions/webhook/client.rb
+- lib/legion/extensions/webhook/helpers/client.rb
+- lib/legion/extensions/webhook/helpers/signature.rb
+- lib/legion/extensions/webhook/runners/endpoints.rb
+- lib/legion/extensions/webhook/runners/receive.rb
+- lib/legion/extensions/webhook/runners/verify.rb
+- lib/legion/extensions/webhook/version.rb
+homepage: https://github.com/LegionIO/lex-webhook
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-webhook
+  source_code_uri: https://github.com/LegionIO/lex-webhook
+  changelog_uri: https://github.com/LegionIO/lex-webhook/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/LegionIO/lex-webhook
+  bug_tracker_uri: https://github.com/LegionIO/lex-webhook/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Legion::Extensions::Webhook
+test_files: []