moderate 0.1.0 → 1.0.0.beta1

data/Rakefile

@@ -1,4 +1,30 @@
-# frozen_string_literal: true
+begin
+  require "bundler/setup"
+rescue LoadError
+  puts "You must `gem install bundler` and `bundle install` to run rake tasks"
+end
 
 require "bundler/gem_tasks"
-task default: %i[]
+
+require "rdoc/task"
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.title = "Moderate"
+  rdoc.options << "--line-numbers"
+  rdoc.rdoc_files.include("README.md")
+  rdoc.rdoc_files.include("lib/**/*.rb")
+end
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = false
+end
+
+task default: :test

data/app/controllers/concerns/moderate/moderation.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Moderate
+  # Drop-in admin moderation actions for a host's admin controller (BYOUI).
+  #
+  #   class Admin::ReportsController < ApplicationController
+  #     include Moderate::Moderation   # resolve/dismiss (+ uphold/reject) actions
+  #     before_action :require_admin   # you bring auth
+  #   end
+  #
+  # `moderate` deliberately ships NO admin UI — Trust & Safety chrome (branding,
+  # auth, layout) is the part every app wants to own. What it DOES own is the
+  # decision *logic*: every status change must go through the model's atomic
+  # decision method (`resolve!`/`dismiss!`/`uphold!`/`reject!`) so content removal,
+  # bans, the notify/audit hooks, the DSA Art. 17 statement-of-reasons, and the
+  # Art. 20 appeal window all happen together-or-not-at-all. This concern is the
+  # thin HTTP glue that calls those methods, so a host gets the standard wiring for
+  # free and never hand-rolls a raw `status = "..."` update (which would skip every
+  # one of those guarantees). See docs/madmin.md.
+  #
+  # The actions assume `@record` is already loaded (madmin's ResourceController and
+  # most admin frameworks set it from the member route). If yours doesn't, override
+  # `moderation_record` below.
+  module Moderation
+    extend ActiveSupport::Concern
+
+    # --- Report / Flag decisions ---------------------------------------------
+    # Both `Moderate::Report` and `Moderate::Flag` expose `resolve!`/`dismiss!` with
+    # the same keyword contract, so the SAME two actions drive either resource —
+    # the host just includes this concern in whichever controller.
+
+    # Resolve (action) a report/flag: optionally remove the offending content and/or
+    # ban the responsible user, always with a moderator + a note.
+    #
+    # `remove_content`/`ban_user` come from the form as checkboxes ("1"/"0"); the
+    # model casts them, but we pass them through untouched so the model stays the one
+    # place that interprets them. `note` is required by the model (it feeds the
+    # statement of reasons) — we let the model raise and turn that into a flash.
+    def resolve
+      record = moderation_record
+      record.resolve!(**moderation_decision_params)
+      redirect_after_moderation(record, notice: moderation_t(:resolved))
+    rescue => error
+      redirect_after_moderation(record, alert: moderation_error(:resolve, error))
+    end
+
+    # Dismiss (action) a report/flag: no violation found. Note still required.
+    def dismiss
+      record = moderation_record
+      record.dismiss!(by: moderation_actor, note: moderation_note)
+      redirect_after_moderation(record, notice: moderation_t(:dismissed))
+    rescue => error
+      redirect_after_moderation(record, alert: moderation_error(:dismiss, error))
+    end
+
+    # --- Appeal decisions (DSA Art. 20) --------------------------------------
+    # An appeal is a free, electronic, human-decided internal complaint against a
+    # decision. `uphold!` OVERTURNS the original decision; `reject!` CONFIRMS it.
+    # https://eur-lex.europa.eu/eli/reg/2022/2065/oj (Article 20)
+
+    def uphold
+      record = moderation_record
+      record.uphold!(by: moderation_actor, note: moderation_note)
+      redirect_after_moderation(record, notice: moderation_t(:upheld))
+    rescue => error
+      redirect_after_moderation(record, alert: moderation_error(:uphold, error))
+    end
+
+    def reject
+      record = moderation_record
+      record.reject!(by: moderation_actor, note: moderation_note)
+      redirect_after_moderation(record, notice: moderation_t(:rejected))
+    rescue => error
+      redirect_after_moderation(record, alert: moderation_error(:reject, error))
+    end
+
+    private
+
+    # The record being decided on. Override if your admin framework names it
+    # differently — madmin uses `@record`, many hand-rolled admins do too.
+    def moderation_record
+      @record
+    end
+
+    # The moderator making the call. `current_user` is the near-universal accessor;
+    # a host whose admin uses a different actor (e.g. `current_admin`) overrides
+    # this single method. Required by every decision method (the decision must be
+    # attributable to a human — a DSA Art. 17/20 requirement).
+    def moderation_actor
+      current_user
+    end
+
+    # The mandatory decision rationale. Required by the model too (belt and
+    # suspenders) — it's what populates the statement of reasons sent to the parties.
+    def moderation_note
+      params[:note]
+    end
+
+    # Strong params for the richest decision (`resolve` on a report). We don't use
+    # `params.require(:report)` because the decision form is a flat panel of
+    # checkboxes + a note, not a nested model form — so we read top-level params and
+    # hand the model exactly the keyword args it documents. `ban_user`/`remove_content`
+    # default to off so a missing checkbox never accidentally bans someone.
+    def moderation_decision_params
+      {
+        by: moderation_actor,
+        note: moderation_note,
+        remove_content: params[:remove_content],
+        ban_user: params[:ban_user]
+      }
+    end
+
+    # Redirect back to the record after a decision.
+    #
+    # `status: :see_other` (303) is REQUIRED, not stylistic: the decision actions are
+    # POSTs, and Turbo Drive only follows a redirect after a non-GET when the status
+    # is 303 — without it the redirect is swallowed and the page appears to hang.
+    # This is the same convention Rails' own scaffold create/update use.
+    # https://turbo.hotwired.dev/handbook/drive#redirecting-after-a-form-submission
+    #
+    # We fall back to `:back` when we can't build a path for the record, so the
+    # concern works regardless of the host's route names (BYOUI — we don't know
+    # them). The host can override `moderation_redirect_path` for an exact target.
+    def redirect_after_moderation(record, **flash)
+      path = moderation_redirect_path(record)
+      if path
+        redirect_to(path, status: :see_other, **flash)
+      else
+        redirect_back(fallback_location: "/", status: :see_other, **flash)
+      end
+    end
+
+    # Where to go after a decision. Returns nil so `redirect_after_moderation` falls
+    # back to `redirect_back` — the safe default for an admin we know nothing about.
+    # Override in the host controller to land on the record's show page, e.g.
+    #   def moderation_redirect_path(record) = main_app.madmin_report_path(record)
+    def moderation_redirect_path(_record)
+      nil
+    end
+
+    # A flash message for the failure case. We surface the model's own error message
+    # (e.g. "report already closed", "note required") so the moderator sees WHY the
+    # decision didn't apply, not a generic "something went wrong".
+    def moderation_error(action, error)
+      message = error.respond_to?(:message) ? error.message : error.to_s
+      moderation_t(:"#{action}_failed", default: "Could not #{action}: #{message}", error: message)
+    end
+
+    # Translated flash copy, with a plain-English default so the concern works even
+    # before the host loads the gem's locale file.
+    def moderation_t(key, **options)
+      defaults = {
+        resolved: "Report resolved.",
+        dismissed: "Report dismissed.",
+        upheld: "Appeal upheld.",
+        rejected: "Appeal rejected."
+      }
+      I18n.t("moderate.moderation.#{key}", default: options.delete(:default) || defaults[key] || key.to_s, **options)
+    end
+  end
+end

data/app/controllers/moderate/appeals_controller.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module Moderate
+  # Public DSA Art. 20 internal complaint form for moderation decisions.
+  class AppealsController < Moderate::ApplicationController
+    helper_method :turnstile_widget_required?
+
+    before_action :enforce_appeal_enabled!
+    before_action :throttle_appeals!, only: :create
+    before_action :verify_human!, only: :create
+
+    def new
+      @report = Moderate::Report.locate_signed_appeal_report(params[:token])
+      return redirect_to appeal_return_path, alert: t("moderate.appeals.not_found", default: "We couldn't find that moderation decision.") if @report.blank?
+
+      @appeal = Moderate::Appeal.new(
+        report: @report,
+        appellant: current_appellant,
+        appellant_name: current_appellant_name,
+        appellant_email: current_appellant_email,
+        source: appeal_source_for(@report, params[:source])
+      )
+    end
+
+    def create
+      @report = Moderate::Report.locate_signed_appeal_report(params[:token])
+      return redirect_to appeal_return_path, alert: t("moderate.appeals.not_found", default: "We couldn't find that moderation decision.") if @report.blank?
+
+      attributes = appeal_params
+      attributes[:source] = appeal_source_for(@report, attributes[:source])
+
+      intake = Moderate::Services::IntakeAppeal.new(
+        appeal: Moderate::Appeal.new(attributes),
+        report: @report,
+        appellant: current_appellant
+      )
+      @appeal = intake.appeal
+
+      if intake.save
+        redirect_to appeal_return_path,
+          notice: t("moderate.appeals.received", default: "Appeal received. A human reviewer will assess the decision."),
+          status: :see_other
+      else
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    private
+
+    def appeal_params
+      params.require(:appeal).permit(:appellant_name, :appellant_email, :source, :reason)
+    end
+
+    def appeal_source_for(report, requested_source)
+      return "affected_user" if current_appellant.present? && current_appellant.id == report.reported_user_id
+
+      source = requested_source.to_s.squish
+      return "notifier" if source == "affected_user" && report.reported_user_id.blank?
+
+      Moderate::Appeal::SOURCES.include?(source) ? source : "notifier"
+    end
+
+    def current_appellant
+      return @current_appellant if defined?(@current_appellant)
+
+      @current_appellant =
+        if respond_to?(:current_user, true)
+          current_user
+        end
+    rescue StandardError
+      @current_appellant = nil
+    end
+
+    def current_appellant_name
+      current_appellant&.try(:display_name) || current_appellant&.try(:name)
+    end
+
+    def current_appellant_email
+      current_appellant&.try(:email)
+    end
+
+    def appeal_return_path
+      path = Moderate.config.appeal_return_path
+      path = path.call(self) if path.respond_to?(:call)
+      path.presence || "/"
+    end
+
+    def enforce_appeal_enabled!
+      return if Moderate.config.appeal_form_enabled
+
+      raise ActionController::RoutingError, "Moderate appeal form is disabled (config.appeal_form_enabled = false)"
+    end
+
+    def throttle_appeals!
+      limit = Moderate.config.appeal_rate_limit
+      return if limit == false || limit.nil?
+
+      max = limit.fetch(:max, 10)
+      within = limit.fetch(:within, 60).to_i
+
+      key = "moderate:appeal_rate:#{request.remote_ip}"
+      count = rate_limit_increment(key, expires_in: within)
+
+      render_rate_limited if count > max
+    end
+
+    def rate_limit_increment(key, expires_in:)
+      store = Rails.cache
+      return 0 unless store
+
+      current = store.read(key).to_i
+      store.write(key, current + 1, expires_in: expires_in) if current.zero?
+      store.increment(key) || (current + 1)
+    rescue StandardError
+      0
+    end
+
+    def render_rate_limited
+      flash.now[:alert] = t("moderate.appeals.rate_limited", default: "Too many appeals from this address. Please try again later.")
+      rebuild_appeal_from_params
+      render :new, status: :too_many_requests
+    end
+
+    def verify_human!
+      return if human_verification_skipped?
+
+      if turnstile_available?
+        verify_turnstile!
+      else
+        run_appeal_guard!
+      end
+    end
+
+    def turnstile_widget_required?
+      turnstile_available? && !human_verification_skipped?
+    end
+
+    def human_verification_skipped?
+      predicate = Moderate.config.appeal_human_verification_skip_if
+      return false unless predicate.respond_to?(:call)
+
+      predicate.call(self) ? true : false
+    rescue StandardError
+      false
+    end
+
+    def turnstile_available?
+      defined?(::RailsCloudflareTurnstile) && respond_to?(:validate_cloudflare_turnstile, true)
+    end
+
+    def verify_turnstile!
+      validate_cloudflare_turnstile
+    rescue ::RailsCloudflareTurnstile::Forbidden
+      render_captcha_failed
+    end
+
+    def run_appeal_guard!
+      guard = Moderate.config.appeal_guard
+      return unless guard.respond_to?(:call)
+      return if safe_call_guard(guard)
+
+      render_captcha_failed
+    end
+
+    def safe_call_guard(guard)
+      guard.call(self) ? true : false
+    rescue StandardError
+      false
+    end
+
+    def render_captcha_failed
+      flash.now[:alert] = t("moderate.appeals.captcha_failed", default: "We couldn't verify you're human. Please try the check again.")
+      rebuild_appeal_from_params
+      render :new, status: :unprocessable_entity
+    end
+
+    def rebuild_appeal_from_params
+      @report ||= Moderate::Report.locate_signed_appeal_report(params[:token])
+      @appeal = Moderate::Appeal.new(appeal_params_safe)
+      @appeal.report = @report if @report
+      @appeal.source = appeal_source_for(@report, @appeal.source) if @report
+    end
+
+    def appeal_params_safe
+      appeal_params.to_h
+    rescue ActionController::ParameterMissing
+      {}
+    end
+  end
+end

data/app/controllers/moderate/application_controller.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Moderate
+  # Base controller for the engine's OWN controllers (today: the public DSA notice
+  # form). It is NOT used by the host's in-app report/admin controllers — those are
+  # BYOUI and inherit from the host's own ApplicationController.
+  #
+  # The parent class is INDIRECTED through `config.parent_controller`
+  # (default `"::ActionController::Base"`), exactly the `config.parent_controller`
+  # trick Devise and `api_keys` use. Why indirect instead of just inheriting from
+  # `ActionController::Base`?
+  #   - On an API-only app there is no `ActionController::Base` view stack by
+  #     default; defaulting to it (and pulling in the view modules below) keeps the
+  #     HTML notice form working even there.
+  #   - A host that wants the public forms to sit inside its own site chrome points
+  #     `config.parent_controller` at its own base controller and inherits
+  #     its layout, locale-setting, current_user, etc. — without us hard-coding any
+  #     of that.
+  #
+  # We resolve the parent at class-definition time via `Class.new(...)` + a
+  # `const_set`-free `superclass` trick: Ruby can't change a class's superclass
+  # after definition, so we constantize the configured name HERE, on first load of
+  # this file. The configured value is a STRING constantized lazily, consistent with
+  # the rest of the gem's "store class names as strings" rule.
+  parent = begin
+    Moderate.config.parent_controller.to_s.constantize
+  rescue NameError
+    # Defensive fallback: if the configured parent isn't loadable (typo, or an
+    # API-only app without ActionController::Base required yet), fall back to the
+    # stock base so the engine still boots. ActionController::Base is part of Rails.
+    require "action_controller"
+    ::ActionController::Base
+  end
+
+  class ApplicationController < parent
+    # CSRF protection — but only when the parent actually supports it. On
+    # `ActionController::API` (or a host base that doesn't include the module),
+    # `protect_from_forgery` isn't defined, so we guard the call. The public notice
+    # form is a state-changing POST, so we want forgery protection whenever it's
+    # available. `with: :exception` is the modern Rails default.
+    if respond_to?(:protect_from_forgery)
+      protect_from_forgery with: :exception
+    end
+  end
+end