hostily-captcha 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8647978872b4be39152495b93f3d573eaf0a05fef1f56edb6c921339a90d8c3b
+  data.tar.gz: cc9099a1f4326fcff2cbfd6b1acfa4d37c5fe190ee4a46952d8c185ffeeb0b3c
+SHA512:
+  metadata.gz: 171ff9e945d6fc22013145bddf1e3a542bb7c02fa2af3c1598cf7d6c84dca46bef8a950661caefb0882838ffe9f6b709daee206109115bdcc362eb616169b2ac
+  data.tar.gz: 8db216a736510f450334cd9afeb3f2773da9bd0a628e2799d48c57df23e0afe30d5b9edaa03dc31eba6ac1b84e0ec03cbfb642fedd1ef5e2499853781c5ef067

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 connect - Media & Teledienst (hostily)
+
+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,74 @@
+# hostily-captcha (Ruby)
+
+**Deutsch**
+
+Kleiner Client für [hostily Captcha](https://captcha.hostily.de) mit Rails-Helfern. Ruby ≥ 3.1, nur `Net::HTTP` (keine fremden Gems).
+
+```ruby
+gem "hostily-captcha"
+```
+
+**Ohne Rails**
+
+```ruby
+require "hostily/captcha"
+
+captcha = Hostily::Captcha::Client.new(ENV.fetch("HOSTILY_CAPTCHA_SECRET")) # Secret nur auf dem Server!
+begin
+  result = captcha.verify_form(params, remoteip: request.ip)
+rescue Hostily::Captcha::UnavailableError
+  # Dienst nicht erreichbar: blockieren oder durchlassen - Ihre Entscheidung
+end
+puts result.gruende, result.punkte unless result.success?
+```
+
+**Rails** (`config/initializers/hostily_captcha.rb`)
+
+```ruby
+Hostily::Captcha.configure do |c|
+  c.site_key = "…"                              # öffentlich
+  c.secret   = ENV["HOSTILY_CAPTCHA_SECRET"]    # nur auf dem Server
+  # c.endpoint = "https://captcha.hostily.de"   # Vorgabe
+  # c.modus = "sichtbar" | "unsichtbar"; c.sprache = "de" | "en" (Vorgabe: Seitensprache)
+  # c.fail_open = true                          # Dienst down: durchlassen (Vorgabe); false = blockieren
+end
+```
+
+```erb
+<%= form_with url: contact_path do |f| %>
+  …
+  <%= hostily_captcha_tag %>     <%# Widget + Skript; Optionen: site_key:, modus:, sprache:, api:, script: false %>
+<% end %>
+```
+
+```ruby
+def create
+  return render(:new, status: :unprocessable_entity) unless verify_hostily_captcha
+  …
+end
+```
+
+`verify_hostily_captcha(fail_open: nil, send_content: true)` liefert `true` (weiter) oder `false`. Ohne Site-Key und Secret wird
+nichts geprüft. Ist der Dienst nicht erreichbar oder das Secret falsch, gilt `fail_open` und die Meldung steht im Rails-Log (nie das
+Secret). `hostily_captcha_result` gibt das letzte Ergebnis zurück. Hinter einem Proxy liefert `request.remote_ip` die echte Adresse.
+
+* `token_from(form)` / `content(form)`: Letzteres entfernt Passwortfelder, Secrets, CSRF-Token, Kartencodes und die Token-Felder,
+  auch in verschachtelten Hashes (`ActionController::Parameters` wird unterstützt). Passwörter werden nie mitgeschickt.
+* `Result`: `success?`, `gruende`, `punkte`, `error_codes`, `hostname`, `configuration_error?`.
+* `timeout:` in Sekunden (Vorgabe 5). Ohne Token wird der Dienst nicht gefragt (`token_fehlt`). Ein Token gilt nur für eine Prüfung.
+* Getestet mit Ruby 3.1 und 3.4; Rails-Helfer mit actionpack (aktuell). Tests: `rake test`.
+
+**English**
+
+Small client for [hostily Captcha](https://captcha.hostily.de) with Rails helpers. Ruby ≥ 3.1, `Net::HTTP` only (no third-party gems).
+
+* Without Rails: `Hostily::Captcha::Client.new(secret).verify_form(params, remoteip: ip)`; `UnavailableError` means the service is
+  unreachable / timed out / HTTP 5xx or 429 / unreadable answer - you decide to block or let pass.
+* Rails: configure in an initializer (see above), put `<%= hostily_captcha_tag %>` into the form, call `verify_hostily_captcha` in the
+  controller (`true` = go on, `false` = reject). Nothing is checked without site key and secret; on an outage or a wrong secret
+  `fail_open` decides (default: let pass) and a line goes to the Rails log (never the secret).
+* `content(form)` drops password fields, secrets, CSRF tokens, card codes and the token fields (also nested). Passwords are never sent.
+* `Result`: `success?`, `gruende`, `punkte`, `error_codes`, `hostname`, `configuration_error?`. Default timeout 5 s.
+  A token is valid for one check only. Tests: `rake test`.
+
+MIT License.

data/lib/hostily/captcha/client.rb

@@ -0,0 +1,113 @@
+require "json"
+require "openssl"
+require "net/http"
+require "uri"
+
+module Hostily
+  module Captcha
+    DEFAULT_ENDPOINT = "https://captcha.hostily.de".freeze
+    TOKEN_FIELDS = %w[hostily-captcha-token g-recaptcha-response].freeze
+    SENSITIVE = /pass(word|wort|wd|phrase|code)|(^|[_\-\[])pass($|[_\-\]])|pwd|secret|csrf|xsrf|token|cvc|cvv/i
+
+    # The service could not be reached or answered unusably (network, timeout, HTTP 5xx/429, no JSON).
+    # The caller decides: let the request pass (fail open) or block it (fail closed).
+    class UnavailableError < StandardError; end
+
+    Result = Struct.new(:success, :gruende, :punkte, :error_codes, :hostname, :challenge_ts, keyword_init: true) do
+      def self.from_hash(h)
+        new(success: h["success"] == true, gruende: Array(h["gruende"]).map(&:to_s), punkte: h["punkte"],
+            error_codes: Array(h["error-codes"]).map(&:to_s), hostname: h["hostname"].to_s, challenge_ts: h["challenge_ts"])
+      end
+
+      def success? = success
+
+      # Secret missing or wrong: a configuration problem, not a spam verdict.
+      def configuration_error?
+        !(error_codes & %w[missing-input-secret invalid-input-secret]).empty?
+      end
+    end
+
+    # Token from a params-like object (Hash, ActionController::Parameters, ...).
+    def self.token_from(form)
+      TOKEN_FIELDS.each do |name|
+        v = form[name]
+        v = form[name.to_sym] if v.nil? && form.respond_to?(:key?) && form.key?(name.to_sym)
+        return v.strip if v.is_a?(String) && !v.strip.empty?
+      end
+      nil
+    end
+
+    # Form content for rule/honeypot checks. Token fields and anything that looks like a password, secret,
+    # CSRF token or card code are removed (also in nested hashes).
+    def self.content(form, exclude = [])
+      form = form.to_unsafe_h if form.respond_to?(:to_unsafe_h)
+      out = {}
+      form.each do |name, value|
+        key = name.to_s
+        next if TOKEN_FIELDS.include?(key) || exclude.include?(key) || SENSITIVE.match?(key)
+
+        value = value.to_unsafe_h if value.respond_to?(:to_unsafe_h)
+        out[key] =
+          case value
+          when Hash then content(value, exclude)
+          when Array then value.map { |v| v.is_a?(Hash) ? content(v, exclude) : v.to_s }
+          when String, Numeric, true, false, nil then value.to_s
+          else next
+          end
+      end
+      out
+    end
+
+    class Client
+      attr_reader :endpoint, :timeout
+
+      def initialize(secret, endpoint: DEFAULT_ENDPOINT, timeout: 5.0)
+        @secret = secret
+        @endpoint = endpoint.to_s.sub(%r{/+\z}, "")
+        @timeout = timeout
+      end
+
+      # Raises UnavailableError if the service cannot be reached.
+      def verify(token, remoteip: nil, formular: nil)
+        if token.nil? || token.to_s.strip.empty?
+          return Result.new(success: false, gruende: ["token_fehlt"], punkte: nil, error_codes: ["missing-input-response"], hostname: "", challenge_ts: nil)
+        end
+
+        body = { "secret" => @secret, "response" => token.to_s.strip }
+        body["remoteip"] = remoteip if remoteip && !remoteip.to_s.empty?
+        body["formular"] = formular unless formular.nil?
+        status, raw = post(JSON.generate(body))
+        data = begin
+          JSON.parse(raw)
+        rescue JSON::ParserError, TypeError
+          nil
+        end
+        if status >= 500 || status == 429 || !data.is_a?(Hash) || !data.key?("success")
+          raise UnavailableError, "hostily Captcha answered unusably (HTTP #{status})"
+        end
+
+        Result.from_hash(data)
+      end
+
+      def verify_form(form, remoteip: nil, send_content: true)
+        verify(Captcha.token_from(form), remoteip: remoteip, formular: send_content ? Captcha.content(form) : nil)
+      end
+
+      private
+
+      def post(json)
+        uri = URI.parse("#{@endpoint}/api/v1/pruefen")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = http.read_timeout = http.write_timeout = @timeout
+        req = Net::HTTP::Post.new(uri.request_uri, "Content-Type" => "application/json", "Accept" => "application/json",
+                                                   "User-Agent" => "hostily-captcha-ruby/#{VERSION}")
+        req.body = json
+        res = http.request(req)
+        [res.code.to_i, res.body.to_s]
+      rescue SystemCallError, SocketError, IOError, Timeout::Error, OpenSSL::SSL::SSLError, URI::InvalidURIError, EOFError, Net::ProtocolError => e
+        raise UnavailableError, "hostily Captcha not reachable: #{e.message}"
+      end
+    end
+  end
+end

data/lib/hostily/captcha/rails.rb

@@ -0,0 +1,72 @@
+require "cgi"
+
+module Hostily
+  module Captcha
+    # View helper: <%= hostily_captcha_tag %> inside the <form>. Settings come from Hostily::Captcha.configuration.
+    module ViewHelper
+      # Widget element (and, unless script: false, the widget script). Options: site_key, modus, sprache, api.
+      def hostily_captcha_tag(site_key: nil, modus: nil, sprache: nil, api: nil, script: true)
+        c = Hostily::Captcha.configuration
+        key = site_key || c.site_key
+        return hostily_captcha_html("") if key.to_s.empty? # not configured: nothing to show
+
+        base = (api || c.endpoint).to_s.sub(%r{/+\z}, "")
+        attrs = { "data-site-key" => key, "data-api" => "#{base}/api/", "data-modus" => modus || c.modus }
+        sp = sprache || c.sprache
+        attrs["data-sprache"] = sp if sp
+        html = +""
+        html << %(<script src="#{CGI.escapeHTML(base)}/widget/hostily-captcha.js" defer></script>\n) if script
+        html << "<hostily-captcha" + attrs.map { |k, v| %( #{k}="#{CGI.escapeHTML(v.to_s)}") }.join + "></hostily-captcha>"
+        hostily_captcha_html(html)
+      end
+
+      private
+
+      def hostily_captcha_html(str)
+        str.respond_to?(:html_safe) ? str.html_safe : str
+      end
+    end
+
+    # Controller method: verify_hostily_captcha -> true (pass) / false (reject). Rejections are logged.
+    module ControllerMethods
+      # fail_open: nil takes Hostily::Captcha.configuration.fail_open. Without secret + site key nothing is checked.
+      def verify_hostily_captcha(fail_open: nil, send_content: true)
+        c = Hostily::Captcha.configuration
+        return true if c.secret.to_s.empty? || c.site_key.to_s.empty?
+
+        fail_open = c.fail_open if fail_open.nil?
+        result = Hostily::Captcha.client.verify_form(params, remoteip: request.remote_ip, send_content: send_content)
+        if result.configuration_error?
+          hostily_captcha_log(:error, "secret missing or wrong (#{result.error_codes.join(',')})")
+          return fail_open
+        end
+        @hostily_captcha_result = result
+        result.success?
+      rescue Hostily::Captcha::UnavailableError => e
+        hostily_captcha_log(:warn, e.message)
+        fail_open
+      end
+
+      # Result of the last check (nil if the service was down, not configured or the secret was wrong).
+      def hostily_captcha_result
+        @hostily_captcha_result
+      end
+
+      private
+
+      def hostily_captcha_log(level, message)
+        l = respond_to?(:logger, true) ? logger : nil
+        l&.public_send(level, "[hostily-captcha] #{message}") # never the secret
+      end
+    end
+
+    if defined?(::Rails::Railtie)
+      class Railtie < ::Rails::Railtie
+        initializer "hostily_captcha.helpers" do
+          ActiveSupport.on_load(:action_view) { include Hostily::Captcha::ViewHelper }
+          ActiveSupport.on_load(:action_controller) { include Hostily::Captcha::ControllerMethods }
+        end
+      end
+    end
+  end
+end

data/lib/hostily/captcha/version.rb

@@ -0,0 +1,5 @@
+module Hostily
+  module Captcha
+    VERSION = "0.1.0"
+  end
+end

data/lib/hostily/captcha.rb

@@ -0,0 +1,35 @@
+require "hostily/captcha/version"
+require "hostily/captcha/client"
+require "hostily/captcha/rails"
+
+module Hostily
+  module Captcha
+    class Configuration
+      attr_accessor :secret, :site_key, :endpoint, :timeout, :modus, :sprache, :fail_open
+
+      def initialize
+        @endpoint = DEFAULT_ENDPOINT
+        @timeout = 5.0
+        @modus = "sichtbar"
+        @sprache = nil # nil: the widget decides (page language)
+        @fail_open = true # service down: let the request pass (false: block)
+      end
+    end
+
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield configuration
+      end
+
+      # Client from the global configuration.
+      def client
+        c = configuration
+        Client.new(c.secret.to_s, endpoint: c.endpoint, timeout: c.timeout)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: hostily-captcha
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- connect - Media & Teledienst
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-30 00:00:00.000000000 Z
+dependencies: []
+description: Verify the token of a submitted form against hostily Captcha. Net::HTTP
+  only; optional Rails view helper and controller method.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/hostily/captcha.rb
+- lib/hostily/captcha/client.rb
+- lib/hostily/captcha/rails.rb
+- lib/hostily/captcha/version.rb
+homepage: https://captcha.hostily.de
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/connect-gruppe/hostily-captcha-ruby
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Server-side client for hostily Captcha (captcha.hostily.de), with Rails helpers
+test_files: []