xlock 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1420010c44730cf9ba48ffab54e85fcd358de4eb89a3e5611731552d4755c8a4
+  data.tar.gz: 7ee393ae2ba3a0fd4339d1fd6334c8e51368cdd26c8e02e27a86f70e04e7746e
+SHA512:
+  metadata.gz: 0befae735395708c8fcdaf61d9b814b27cd745b698a3ae4087e5e873cd82ee963fd099ba2740624edbff932ced338eb5ab5d2fc1e8bb426a86e7636f9fc4351f
+  data.tar.gz: 23a5b02aa8ae5f0ba63f08527473f2bfbc90e3ad551a07030b80fd02c8ad30bff4665f4cdb4fad9adfa9289fd0e99d6b8fbecb9f5d81de2026146fce19697fa8

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 x-lock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,64 @@
+# xlock
+
+Server-side bot protection middleware for Ruby. Works with Rack, Rails, or standalone.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "xlock"
+```
+
+Then run `bundle install`.
+
+## Usage
+
+### Rails Controller
+
+```ruby
+class ApplicationController < ActionController::Base
+  include XLock::Rails
+
+  protect_with_xlock only: [:create, :login],
+    site_key: ENV["XLOCK_SITE_KEY"]
+end
+```
+
+Options: `site_key`, `api_url`, `fail_open` (default `true`).
+
+### Rack Middleware
+
+```ruby
+use XLock::Rack,
+  site_key: ENV["XLOCK_SITE_KEY"],
+  protected_paths: ["/api/auth", "/api/login"]
+```
+
+Only POST requests to the listed paths are checked. If `protected_paths` is empty, all POST requests are checked.
+
+### Direct Verification
+
+```ruby
+result = XLock.verify(
+  token: "...",
+  site_key: ENV["XLOCK_SITE_KEY"],
+  path: "/api/login"
+)
+
+if result.blocked
+  puts "Blocked: #{result.reason}"
+elsif result.error
+  puts "Error: #{result.error}"
+else
+  puts "Allowed"
+end
+```
+
+## Configuration
+
+Set `XLOCK_SITE_KEY` and optionally `XLOCK_API_URL` as environment variables, or pass them directly as options.
+
+## License
+
+MIT

data/lib/xlock/rack.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module XLock
+  # Rack middleware for x-lock bot protection.
+  #
+  # Usage:
+  #   use XLock::Rack,
+  #     site_key: ENV["XLOCK_SITE_KEY"],
+  #     protected_paths: ["/api/auth"]
+  class Rack
+    def initialize(app, **options)
+      @app = app
+      @site_key = options[:site_key] || ENV["XLOCK_SITE_KEY"]
+      @api_url = options[:api_url] || XLock::API_URL
+      @fail_open = options.fetch(:fail_open, true)
+      @protected_paths = options[:protected_paths] || []
+    end
+
+    def call(env)
+      request = ::Rack::Request.new(env)
+
+      unless @site_key && request.post? && matches?(request.path)
+        return @app.call(env)
+      end
+
+      token = env["HTTP_X_LOCK"]
+      unless token
+        return [403, { "Content-Type" => "application/json" },
+                ['{"error":"Blocked by x-lock: missing token"}']]
+      end
+
+      result = XLock.verify(token: token, site_key: @site_key, path: request.path, api_url: @api_url)
+
+      if result.blocked
+        return [403, { "Content-Type" => "application/json" },
+                [{ error: "Blocked by x-lock", reason: result.reason }.to_json]]
+      end
+
+      if result.error && !@fail_open
+        return [403, { "Content-Type" => "application/json" },
+                ['{"error":"x-lock verification failed"}']]
+      end
+
+      @app.call(env)
+    end
+
+    private
+
+    def matches?(path)
+      return true if @protected_paths.empty?
+      @protected_paths.any? { |p| path.start_with?(p) }
+    end
+  end
+end

data/lib/xlock/rails.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module XLock
+  # Rails controller concern for x-lock bot protection.
+  #
+  # Usage:
+  #   class ApplicationController < ActionController::Base
+  #     include XLock::Rails
+  #     protect_with_xlock only: [:create, :login],
+  #       site_key: ENV["XLOCK_SITE_KEY"]
+  #   end
+  module Rails
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def protect_with_xlock(**options)
+        before_action :enforce_xlock!, **options.except(:site_key, :api_url, :fail_open)
+
+        define_method(:xlock_config) do
+          {
+            site_key: options[:site_key] || ENV["XLOCK_SITE_KEY"],
+            api_url: options[:api_url] || XLock::API_URL,
+            fail_open: options.fetch(:fail_open, true)
+          }
+        end
+        private :xlock_config
+      end
+    end
+
+    private
+
+    def enforce_xlock!
+      config = xlock_config
+      return unless config[:site_key]
+
+      token = request.headers["x-lock"]
+      unless token
+        render json: { error: "Blocked by x-lock: missing token" }, status: 403
+        return
+      end
+
+      result = XLock.verify(
+        token: token,
+        site_key: config[:site_key],
+        path: request.path,
+        api_url: config[:api_url]
+      )
+
+      if result.blocked
+        render json: { error: "Blocked by x-lock", reason: result.reason }, status: 403
+        return
+      end
+
+      if result.error
+        if config[:fail_open]
+          ::Rails.logger.error("[x-lock] Enforcement error: #{result.error}") if defined?(::Rails.logger)
+        else
+          render json: { error: "x-lock verification failed" }, status: 403
+        end
+      end
+    end
+  end
+end

data/lib/xlock/verify.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require "ostruct"
+
+module XLock
+  API_URL = ENV.fetch("XLOCK_API_URL", "https://api.x-lock.dev")
+
+  # Verify an x-lock token against the API.
+  #
+  # @param token [String] the x-lock token from the client
+  # @param site_key [String] your site key
+  # @param path [String] the request path being protected
+  # @param api_url [String] override the API endpoint
+  # @return [OpenStruct] with :blocked (Boolean), :reason (String|nil), :error (String|nil)
+  def self.verify(token:, site_key:, path: "/", api_url: API_URL)
+    if token.start_with?("v3.")
+      session_id = token.split(".")[1]
+      uri = URI("#{api_url}/v3/session/enforce")
+      body = { sessionId: session_id, siteKey: site_key, path: path }
+    else
+      uri = URI("#{api_url}/v1/enforce")
+      body = { token: token, siteKey: site_key, path: path }
+    end
+
+    http = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl = uri.scheme == "https"
+    http.open_timeout = 5
+    http.read_timeout = 5
+
+    req = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
+    req.body = body.to_json
+
+    res = http.request(req)
+
+    if res.code == "403"
+      data = JSON.parse(res.body) rescue {}
+      OpenStruct.new(blocked: true, reason: data["reason"], error: nil)
+    elsif res.is_a?(Net::HTTPSuccess)
+      OpenStruct.new(blocked: false, reason: nil, error: nil)
+    else
+      OpenStruct.new(blocked: false, reason: nil, error: "Unexpected status #{res.code}")
+    end
+  rescue => e
+    OpenStruct.new(blocked: false, reason: nil, error: e.message)
+  end
+end

data/lib/xlock/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module XLock
+  VERSION = "0.1.0"
+end

data/lib/xlock.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "xlock/version"
+require_relative "xlock/verify"
+require_relative "xlock/rack"
+require_relative "xlock/rails"

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: xlock
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- x-lock
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-04-05 00:00:00.000000000 Z
+dependencies: []
+description: Server-side token verification and Rack/Rails middleware for x-lock bot
+  protection.
+email:
+- support@x-lock.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/xlock.rb
+- lib/xlock/rack.rb
+- lib/xlock/rails.rb
+- lib/xlock/verify.rb
+- lib/xlock/version.rb
+homepage: https://x-lock.dev
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://x-lock.dev
+  source_code_uri: https://github.com/x-lock/xlock-ruby
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: x-lock bot protection middleware for Ruby
+test_files: []