moderate 0.1.0 → 1.0.0.beta1

data/app/controllers/moderate/notices_controller.rb

@@ -0,0 +1,382 @@
+# frozen_string_literal: true
+
+module Moderate
+  # The PUBLIC, regulator-facing DSA "notice and action" intake form.
+  #
+  # The EU Digital Services Act, Article 16, requires every hosting service serving
+  # EU users to offer a PUBLIC, ELECTRONIC mechanism for ANYONE (not just logged-in
+  # users) to flag illegal content, and to ACKNOWLEDGE receipt of that notice. This
+  # controller is that mechanism — the "Report illegal content (EU)" form you see at
+  # the bottom of X / YouTube / Reddit. It is separate from the in-app "Report"
+  # button (that's the host's BYOUI report controller) and from the admin queue.
+  # See: https://eur-lex.europa.eu/eli/reg/2022/2065/oj  (Article 16)
+  #
+  # The controller is intentionally boring: it does HTTP only. All the Trust &
+  # Safety work — the Art. 16 field validations, the immutable evidence snapshot,
+  # the durable acknowledgement (Art. 16(4)), dropping the row into
+  # `Moderate::Report.pending`, and firing the `notice_received` confirmation-of-
+  # receipt event — lives in the model/service (`Moderate::Services::IntakeNotice`
+  # building a `Moderate::Report` with `intake_kind: "dsa"`), never here.
+  #
+  # A notice is NOT a fourth table: it is a `Moderate::Report` with
+  # `intake_kind: "dsa"`, sharing the same queue, snapshot, appeal window, and Art.
+  # 24 transparency counters as an in-app report. One queue, two front doors.
+  class NoticesController < Moderate::ApplicationController
+    helper_method :turnstile_widget_required?
+
+    # Hard kill-switch: if a host sets `config.notice_form_enabled = false`, the
+    # whole engine surface 404s. Lets an app mount the engine but disable the form
+    # (e.g. it doesn't serve EU users) without un-mounting routes.
+    before_action :enforce_notice_enabled!
+
+    # Anti-abuse, defense-in-depth, applied only to the state-changing POST. Both
+    # gates degrade to "off" gracefully so the form is never a support burden in
+    # environments that don't need them (dev/test, or apps that gate at the edge).
+    before_action :throttle_notices!, only: :create
+
+    # The bot gate, auto-wired. A single before_action that decides AT REQUEST TIME
+    # which check to run, so the wiring auto-adapts to whether the host has the
+    # `rails_cloudflare_turnstile` gem — no hard dependency, no class-reload to flip
+    # the behavior. See #verify_human! near the bottom of this file for the branch.
+    before_action :verify_human!, only: :create
+
+    # GET /notices/new — the form, prefilled (and partially locked) from the request.
+    #
+    # X-style deep link: a host can link to this form from a piece of content with
+    # the reported-content details already in the query string (content_url,
+    # content_type, content_author, content_id — see #prefill_attributes), so the
+    # notifier doesn't have to copy-paste the URL of what they're flagging. We ALSO
+    # prefill the notifier's identity from Devise `current_user` when someone happens
+    # to be logged in (the form is still public/anonymous-friendly). The view locks
+    # the auto-prefilled IDENTITY fields so they can't be tampered with, while the
+    # reported-content fields stay fully editable. DSA Art. 16(2)(b)/(c).
+    def new
+      @report = Moderate::Report.new(prefill_attributes)
+      @identity_locked = identity_locked?
+    end
+
+    # POST /notices — validate + persist as a DSA-kind Report, fire the confirmation
+    # of receipt, and show the submitter a success page. On failure we re-render the
+    # form with the model's validation errors and a 422 (standard Rails; lets Turbo
+    # replace the form in place).
+    def create
+      @intake = Moderate::Services::IntakeNotice.new(
+        attributes: notice_params,
+        reporter: current_notifier
+      )
+
+      if @intake.save
+        redirect_to(
+          new_notice_path,
+          notice: t("moderate.notices.received", default: "Notice received. We have logged your report and will review it."),
+          status: :see_other
+        )
+      else
+        @report = @intake.report
+        @identity_locked = identity_locked?
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    private
+
+    # --- Prefill (Art. 16(2)(b)/(c)) ------------------------------------------
+
+    # The attributes used to PREFILL the blank form. Two sources, deliberately kept
+    # apart so the view can lock one and leave the other editable:
+    #   * REPORTED-CONTENT fields, from the query string (an X-style deep link). These
+    #     stay EDITABLE — the notifier is allowed to correct the URL or pick a
+    #     different content type.
+    #   * IDENTITY fields, from Devise `current_user`. These are LOCKED by the view
+    #     (readonly/disabled) so a logged-in notifier can't spoof someone else's
+    #     name/email onto a legal notice.
+    def prefill_attributes
+      content_prefill.merge(identity_prefill)
+    end
+
+    # Reported-content prefill from the query string. The param NAMES are the gem's
+    # documented contract (docs/dsa-notice-form.md), chosen to read naturally in a
+    # link and to map cleanly onto the Report's Art. 16 columns:
+    #   content_url    → subject_url    ("the exact electronic location", Art. 16(2)(b))
+    #   content_type   → content_type   (constrained to Report::CONTENT_TYPES; we only
+    #                                     prefill a value the model will accept, so a
+    #                                     junk query param can't pre-poison the select)
+    #   content_author → reported_account_identifier (a host-side handle/username, free text)
+    #   content_id     → reported_account_identifier fallback if no author was given
+    # All are OPTIONAL: a bare /notices/new with no query string renders a blank form.
+    def content_prefill
+      type = params[:content_type].to_s
+      {
+        subject_url: params[:content_url].presence,
+        # Only echo a content_type the model's inclusion validation would accept, so
+        # a crafted ?content_type=<script> can never reach the page as a selected value.
+        content_type: (type.presence if Moderate::Report::CONTENT_TYPES.include?(type)),
+        reported_account_identifier: params[:content_author].presence || params[:content_id].presence
+      }.compact
+    end
+
+    # Identity prefill from the signed-in user, when one exists. We detect Devise (or
+    # any auth that exposes `current_user`) WITHOUT a hard dependency: the engine's
+    # base controller may or may not define `current_user` depending on the host's
+    # `parent_controller`. `respond_to?` keeps the public/anonymous form
+    # working when nobody is logged in (the overwhelmingly common case for Art. 16).
+    # We read name/email via `try` so the host's user class only needs whichever it
+    # actually has. These keys are what the view LOCKS.
+    def identity_prefill
+      user = current_notifier
+      return {} if user.nil?
+
+      {
+        notifier_name: user.try(:display_name) || user.try(:name),
+        notifier_email: user.try(:email)
+      }.compact
+    end
+
+    # Whether the IDENTITY fields are locked (readonly) on the form. They are locked
+    # exactly when there's a signed-in user whose identity we prefilled — so an
+    # anonymous notice keeps name/email editable, and a logged-in notice locks them
+    # against tampering. Passed to the view as `@identity_locked` so the view never
+    # has to reach for `current_user` itself (it isn't exposed as a view helper here).
+    def identity_locked?
+      user = current_notifier
+      return false if user.nil?
+
+      (user.try(:email) || user.try(:display_name) || user.try(:name)).present?
+    end
+
+    # The logged-in submitter, if any — read defensively. The form is PUBLIC: most
+    # notices come from anonymous notifiers, so `current_notifier` is usually nil and
+    # the notice is a name+email-only record (not tied to a User). We only call
+    # `current_user` when the parent controller actually defines it (Devise-style),
+    # so the engine never hard-depends on an auth gem. `defined?` guards the symbol
+    # itself for parents that expose it as a helper_method but not a public method.
+    def current_notifier
+      return @current_notifier if defined?(@current_notifier)
+
+      @current_notifier =
+        if respond_to?(:current_user, true)
+          current_user
+        end
+    rescue StandardError
+      # A host `current_user` that raises (e.g. a not-yet-migrated session) must not
+      # break the public notice form — fall back to "anonymous".
+      @current_notifier = nil
+    end
+
+    # --- Strong params --------------------------------------------------------
+
+    # Strong params — the Art. 16 field set mapped onto the Report columns. These are
+    # the fields the regulation dictates (legal ground, exact URL, substantiated
+    # explanation, notifier identity, member state, good-faith attestation, plus the
+    # content-type bucket the snapshot needs); there's no product decision to make,
+    # so the permit list is fixed.
+    #
+    # SECURITY NOTE — the LOCKED identity fields. The view renders the prefilled
+    # `notifier_name`/`notifier_email` as readonly/disabled for a logged-in notifier;
+    # a *disabled* field is NOT submitted by the browser, so on create we re-derive
+    # identity from `current_user` and OVERWRITE whatever the params carried. That way
+    # a tampered request that re-enables the field and posts a forged name can't land
+    # a spoofed identity on a legal notice. For an anonymous notifier (no
+    # current_user) the posted name/email are used as-is — they're the only identity
+    # there is.
+    def notice_params
+      permitted = params.require(:notice).permit(
+        :legal_reason,                 # DSA statement-of-reasons taxonomy (Art. 17 ground)
+        :legal_country_code,           # ISO-3166 EU/EEA selector — jurisdiction/routing
+        :content_type,                 # host-agnostic CONTENT_TYPES bucket for the snapshot
+        :subject_url,                  # "the exact electronic location" — Art. 16(2)(b)
+        :subject_urls,                 # newline-separated exact locations; normalized by Report
+        :message,                      # "sufficiently substantiated explanation" — Art. 16(2)(a)
+        :reported_account_identifier,  # optional host-side handle the notice is about
+        :notifier_name,                # Art. 16(2)(c)
+        :notifier_email,               # Art. 16(2)(c) — where the confirmation + decision go
+        :good_faith_confirmed,         # Art. 16(2)(d) attestation — must be checked
+        :anonymous                     # the narrow Art. 16(2)(c) minors carve-out
+      )
+
+      enforce_locked_identity(permitted)
+    end
+
+    # Re-assert the locked identity from the signed-in user, ignoring whatever the
+    # client posted for name/email. No-op for anonymous notifiers. See the security
+    # note on #notice_params.
+    def enforce_locked_identity(permitted)
+      user = current_notifier
+      return permitted if user.nil?
+
+      name = user.try(:display_name) || user.try(:name)
+      email = user.try(:email)
+      permitted[:notifier_name] = name if name.present?
+      permitted[:notifier_email] = email if email.present?
+      permitted
+    end
+
+    # 404 the form when the host has disabled it.
+    def enforce_notice_enabled!
+      return if Moderate.config.notice_form_enabled
+
+      raise ActionController::RoutingError, "Moderate notice form is disabled (config.notice_form_enabled = false)"
+    end
+
+    # --- Rate limit (per-IP throttle) ----------------------------------------
+
+    # A public, unauthenticated POST is a spam/abuse magnet, so we throttle per IP.
+    #
+    # Rails 7.2 shipped a first-class controller `rate_limit` macro; on 7.1 it
+    # doesn't exist, so we fall back to a tiny `Rails.cache`-backed counter. We
+    # implement the throttle as a single `before_action` (rather than the class-level
+    # `rate_limit` macro) precisely so we can honor the host's RUNTIME
+    # `config.notice_rate_limit` (the macro is evaluated at class load, before the
+    # host's initializer has necessarily run).
+    # https://api.rubyonrails.org/classes/ActionController/RateLimiting/ClassMethods.html
+    def throttle_notices!
+      limit = Moderate.config.notice_rate_limit
+      return if limit == false || limit.nil? # explicitly disabled
+
+      max = limit.fetch(:max, 5)
+      within = limit.fetch(:within, 3600).to_i # seconds; the config stores a raw Integer
+
+      key = "moderate:notice_rate:#{request.remote_ip}"
+      count = rate_limit_increment(key, expires_in: within)
+
+      render_rate_limited if count > max
+    end
+
+    # Increment a per-IP counter in the cache, setting the TTL on first write so the
+    # window slides correctly. We guard against a missing cache store (NullStore in a
+    # bare test env) by treating "can't count" as "not limited" — the form must never
+    # break just because rate-limiting can't run.
+    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.notices.rate_limited",
+        default: "Too many notices from this address. Please try again later."
+      )
+      @report ||= Moderate::Report.new(prefill_attributes)
+      @identity_locked = identity_locked?
+      render :new, status: :too_many_requests
+    end
+
+    # --- Bot gate (auto-integrates rails_cloudflare_turnstile when present) -----
+
+    # The single, request-time bot gate. Layered so a host gets the right behavior
+    # with zero wiring:
+    #
+    #   1. If the `rails_cloudflare_turnstile` gem is installed, run ITS server-side
+    #      check — the gem auto-includes RailsCloudflareTurnstile::ControllerHelpers
+    #      into every controller (via its railtie's on_load(:action_controller)
+    #      hook), so `validate_cloudflare_turnstile` is an instance method here. That
+    #      method is exactly what the gem's README tells a host to put in a
+    #      before_action; we call it automatically so the host wires NOTHING beyond
+    #      installing the gem + its keys. A failed challenge raises
+    #      RailsCloudflareTurnstile::Forbidden, which we catch and turn into a
+    #      friendly 422 (the submitter retries the check) rather than a raw error.
+    #      https://github.com/instrumentl/rails-cloudflare-turnstile (README)
+    #
+    #   2. Otherwise, fall back to the host-configurable `config.notice_guard` proc
+    #      (no-op by default, so the form just works in dev/test and for apps that
+    #      gate at the edge). The proc receives THIS controller and returns a boolean
+    #      (truthy ⇒ allowed). A host on hCaptcha / reCAPTCHA / their own check wires
+    #      it; a host on Cloudflare Turnstile installs the gem and gets path (1) free.
+    #
+    # Detection is via `defined?`/`respond_to?` with NO hard dependency in the
+    # gemspec, decided at REQUEST time so the wiring auto-adapts to the bundle.
+    def verify_human!
+      return if human_verification_skipped?
+
+      if turnstile_available?
+        verify_turnstile!
+      else
+        run_notice_guard!
+      end
+    end
+
+    def turnstile_widget_required?
+      turnstile_available? && !human_verification_skipped?
+    end
+
+    def human_verification_skipped?
+      predicate = Moderate.config.notice_human_verification_skip_if
+      return false unless predicate.respond_to?(:call)
+
+      predicate.call(self) ? true : false
+    rescue StandardError
+      false
+    end
+
+    # True when the gem is loaded AND its controller helper is mixed in here, so a
+    # half-loaded/renamed gem can never put us on a path whose method doesn't exist.
+    def turnstile_available?
+      defined?(::RailsCloudflareTurnstile) && respond_to?(:validate_cloudflare_turnstile, true)
+    end
+
+    # Run the gem's verifier, translating its `Forbidden` into our friendly 422. We
+    # reference the exception class by `defined?`-guarded constant so this file never
+    # hard-names a constant that may not exist (the gem is optional).
+    def verify_turnstile!
+      validate_cloudflare_turnstile
+    rescue ::RailsCloudflareTurnstile::Forbidden
+      render_captcha_failed
+    end
+
+    # The gem-absent fallback gate (see #verify_human! point 2). We read the guard
+    # via `respond_to?` so the form still works on a Configuration that predates the
+    # `notice_guard` accessor (treated as "no guard" ⇒ the form just works).
+    def run_notice_guard!
+      return unless Moderate.config.respond_to?(:notice_guard)
+
+      guard = Moderate.config.notice_guard
+      return unless guard.respond_to?(:call)
+      return if truthy?(safe_call_guard(guard))
+
+      render_captcha_failed
+    end
+
+    # Never let a flaky/broken guard raise into the request — a bot service must not
+    # 500 a legal notice form. An exception is treated as "failed closed" (we can't
+    # prove the human), which re-renders the form so the submitter can retry.
+    def safe_call_guard(guard)
+      guard.call(self)
+    rescue StandardError
+      false
+    end
+
+    # Shared failure renderer for BOTH gate paths (a failed Turnstile challenge and a
+    # falsy/raising guard). Re-renders `new` with a friendly 422 so the submitter can
+    # try the check again. We rebuild a prefilled (and re-locked) report so the form
+    # comes back populated rather than blank.
+    def render_captcha_failed
+      flash.now[:alert] = t(
+        "moderate.notices.captcha_failed",
+        default: "We couldn't verify you're human. Please try the check again."
+      )
+      @report ||= Moderate::Report.new(prefill_attributes.merge(notice_params_safe))
+      @identity_locked = identity_locked?
+      render :new, status: :unprocessable_entity
+    end
+
+    # Like `notice_params` but as a plain SYMBOL-keyed Hash and tolerant of a missing
+    # `notice` key, so re-rendering after a failed gate (where params may be partial)
+    # never raises — and so it merges cleanly over the symbol-keyed `prefill_attributes`
+    # (a string-keyed Parameters would create duplicate logical keys and not override).
+    def notice_params_safe
+      notice_params.to_h.symbolize_keys
+    rescue ActionController::ParameterMissing
+      {}
+    end
+
+    def truthy?(value)
+      value ? true : false
+    end
+  end
+end

data/app/controllers/moderate/transparency_reports_controller.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Moderate
+  # Public aggregate transparency report for moderation intake, decisions, appeals,
+  # and automated flags.
+  class TransparencyReportsController < Moderate::ApplicationController
+    before_action :ensure_transparency_report_enabled!
+
+    def show
+      @period_start = 1.year.ago.beginning_of_day
+      @period_end = Time.current
+      # The aggregation is a public facade method so a host that keeps this page off
+      # (it's opt-in) can still call `Moderate.transparency(from:, to:)` to publish
+      # its own report. The view renders the same hash either way.
+      @summary = Moderate.transparency(from: @period_start, to: @period_end)
+    end
+
+    private
+
+    # Hard kill-switch: the public transparency report is OFF unless the host opts
+    # in with `config.transparency_report_enabled = true`. Raising RoutingError makes
+    # the mounted route behave as if it doesn't exist (a 404), same pattern as the
+    # notice/appeal form kill-switches.
+    def ensure_transparency_report_enabled!
+      return if Moderate.config.transparency_report_enabled
+
+      raise ActionController::RoutingError, "Moderate transparency report is disabled (config.transparency_report_enabled = false)"
+    end
+  end
+end

data/app/helpers/moderate/engine_helper.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Moderate
+  # View helpers exposed to BOTH the engine's own views and the HOST app's views.
+  #
+  # The headline helper is `moderate_report_link` (and its terser alias
+  # `report_link`): a one-liner you drop next to any reportable piece of content to
+  # render an in-app "Report" affordance — the exact thing Apple Guideline 1.2 and
+  # Google Play's UGC policy require every social/UGC app to surface next to
+  # user-generated content.
+  #   - https://developer.apple.com/app-store/review/guidelines/#user-generated-content
+  #   - https://support.google.com/googleplay/android-developer/answer/9876937
+  #
+  # GOTCHA — isolated engine + host views: `Moderate::Engine` is an *isolated*
+  # engine (`isolate_namespace Moderate`). Rails does NOT auto-include an isolated
+  # engine's helpers into the host application's views — that's the whole point of
+  # isolation. But `moderate_report_link` is meant to be called from the host's own
+  # templates (e.g. `<%= moderate_report_link(@comment, field: :body) %>`), so we
+  # explicitly mix this module into ActionView for the host at load time via the
+  # `ActiveSupport.on_load(:action_view)` hook at the bottom of this file. That is
+  # the same trick Devise uses to expose its url helpers app-wide.
+  module EngineHelper
+    # Render an in-app report affordance for `record`'s `field`, or NOTHING when the
+    # current viewer isn't allowed to report it.
+    #
+    # Renders nothing (returns nil) — deliberately, and in three cases:
+    #   1. there is no signed-in viewer (anonymous users use the public DSA notice
+    #      form instead; this is the *in-app* button), or
+    #   2. the record doesn't know how to be reported (no `report_visible_to?`), or
+    #   3. the record says this viewer may not report this field
+    #      (`record.report_visible_to?(viewer, field:)` is false — e.g. you can't
+    #      report your own content, or content you can't even see).
+    #
+    # This "render nothing unless permitted" contract is what lets a host sprinkle
+    # the helper liberally across a template without guarding each call site — the
+    # helper is the guard. It mirrors the reference app's `report_link`.
+    #
+    # @param record  [Object] any model that `include`s Moderate::Reportable
+    # @param field   [Symbol, String, nil] which field is being reported (nil =>
+    #   the whole record). Passed straight through to the visibility check and the
+    #   intake form so the moderator sees exactly which field was flagged.
+    # @param label   [String, nil] the visible link text. Defaults to a translated
+    #   "Report" string so the host gets i18n for free.
+    # @param html_options [Hash] extra HTML attributes merged onto the <a> (class,
+    #   data-*, aria-*, …) so the host can style it to taste without a wrapper.
+    # @return [ActiveSupport::SafeBuffer, nil]
+    def moderate_report_link(record, field: nil, label: nil, **html_options)
+      viewer = moderate_current_viewer
+      return if viewer.nil?
+
+      # The record gates its own reportability. We `respond_to?`-guard so a host can
+      # pass any object without the helper exploding — a non-reportable object simply
+      # renders nothing, same as "not permitted".
+      return unless record.respond_to?(:report_visible_to?)
+      return unless record.report_visible_to?(viewer, field: field)
+
+      label ||= moderate_report_default_label
+      link_to(label, moderate_report_path_for(record, field: field), **html_options)
+    end
+
+    # Terse alias. The README/docs use `moderate_report_link` in host views (to
+    # avoid clashing with a host's own `report_link`), but `report_link` reads
+    # cleanest inside the engine's own templates. Same method, two names.
+    def report_link(record, field: nil, label: nil, **html_options)
+      moderate_report_link(record, field: field, label: label, **html_options)
+    end
+
+    private
+
+    # The path to the in-app intake form for this record/field.
+    #
+    # The target is passed as a SIGNED Global ID, never a raw `type`+`id`. This is
+    # the load-bearing security decision of the report flow: a raw polymorphic
+    # `reportable_type`/`reportable_id` pair in a URL is attacker-controlled — anyone
+    # could file a report against an arbitrary record (or probe which ids exist).
+    # A signed GID is tamper-proof and scoped to a single purpose, so the intake
+    # controller can `locate_signed_reportable` it back to the exact record the host
+    # chose to expose here, and nothing else.
+    # See: https://api.rubyonrails.org/classes/GlobalID/Identification.html#method-i-to_sgid
+    #
+    # NOTE: the in-app report controller/route is the host's (BYOUI) — `moderate`
+    # ships the primitives, not the in-app report UI. So we build the path from the
+    # host's named route (`new_report_path`/`new_moderate_report_path`) when present
+    # and fall back to a conventional `/reports/new?target=…` otherwise, rather than
+    # hard-coding the engine's routes (which only cover the *public* DSA form).
+    def moderate_report_path_for(record, field:)
+      target = moderate_signed_target(record)
+      query = { target: target, field: field.presence }.compact
+
+      if respond_to?(:new_report_path)
+        new_report_path(query)
+      elsif respond_to?(:new_moderate_report_path)
+        new_moderate_report_path(query)
+      else
+        # Last-resort conventional path so the helper is never a hard dependency on
+        # a particular route name. The host wires the actual route (BYOUI).
+        "/reports/new?#{query.to_query}"
+      end
+    end
+
+    # The record as a signed, purpose-scoped GID parameter. We delegate to the
+    # Reportable concern's own signer when available (so the purpose/expiry stay in
+    # ONE place — the model), and fall back to `to_sgid_param` with the canonical
+    # purpose otherwise.
+    def moderate_signed_target(record)
+      return record.to_moderation_sgid if record.respond_to?(:to_moderation_sgid)
+
+      # GlobalID's signed param, scoped to a stable purpose string so a token minted
+      # for reporting can't be replayed against an unrelated signed-GID feature.
+      #
+      # `expires_in: nil` mints a NON-EXPIRING token on purpose. By default
+      # `to_sgid_param` bakes in an `exp` timestamp (SignedGlobalID.expires_in, ~1
+      # month), which makes the token — and therefore the rendered link's URL —
+      # CHANGE on every render. That breaks HTTP/fragment caching of pages that show
+      # the report link, and makes the link non-deterministic. The token is already
+      # purpose-scoped ("moderate_report") and the locator restricts resolution to the
+      # allow-listed reportable classes, so a stable, non-expiring identifier is the
+      # right trade-off here: it identifies WHICH record to report, it doesn't grant
+      # any capability that needs to time out.
+      record.to_sgid_param(for: "moderate_report", expires_in: nil)
+    end
+
+    # Who is viewing — resolved without coupling `moderate` to any auth gem. We try
+    # `current_user` (Devise/most apps) first; a host with a different actor accessor
+    # can override `moderate_current_viewer` in their own helper. nil => anonymous,
+    # which correctly hides the in-app button.
+    def moderate_current_viewer
+      return current_user if respond_to?(:current_user)
+
+      nil
+    end
+
+    # Default link text, pulled through I18n so it localizes with the host's locale
+    # and can be overridden without touching call sites. Falls back to plain English
+    # if the host hasn't loaded the gem's locale file.
+    def moderate_report_default_label
+      if defined?(I18n)
+        I18n.t("moderate.report_link.label", default: "Report")
+      else
+        "Report"
+      end
+    end
+  end
+end
+
+# Expose the helper to the HOST app's views (see the "isolated engine" gotcha in
+# the module doc above). `on_load(:action_view)` defers until ActionView is loaded,
+# so we never force it at boot and we play nice with the host's load order.
+ActiveSupport.on_load(:action_view) do
+  include Moderate::EngineHelper
+end if defined?(ActiveSupport)

data/app/views/moderate/appeals/new.html.erb

@@ -0,0 +1,78 @@
+<style>
+  .moderate-page { color: var(--moderate-text, #111827); font-family: var(--moderate-font-family, system-ui, sans-serif); }
+  .moderate-hero { background: var(--moderate-accent, #facc15); padding: 3rem 1.25rem; }
+  .moderate-container { max-width: 42rem; margin: 0 auto; }
+  .moderate-eyebrow { margin: 0; font-size: .75rem; font-weight: 800; text-transform: uppercase; letter-spacing: .12em; color: var(--moderate-muted-text, #374151); }
+  .moderate-title { margin: .5rem 0 0; font-size: clamp(2rem, 6vw, 2.5rem); line-height: 1.1; font-weight: 900; }
+  .moderate-main { padding: 2.5rem 1.25rem; }
+  .moderate-panel { margin-bottom: 1.5rem; border: 1px solid rgba(17, 24, 39, .08); border-radius: .5rem; background: var(--moderate-panel, #f9fafb); padding: 1rem; color: var(--moderate-muted-text, #374151); }
+  .moderate-form { display: grid; gap: 1.25rem; }
+  .moderate-grid { display: grid; gap: 1rem; }
+  @media (min-width: 640px) { .moderate-grid { grid-template-columns: 1fr 1fr; } }
+  .moderate-label { display: block; font-size: .875rem; font-weight: 700; }
+  .moderate-input { box-sizing: border-box; margin-top: .5rem; width: 100%; border: 1px solid rgba(17, 24, 39, .14); border-radius: .5rem; background: white; padding: .75rem 1rem; font: inherit; }
+  .moderate-error { border: 1px solid #fecaca; border-radius: .5rem; background: #fef2f2; padding: .75rem 1rem; color: #991b1b; font-size: .875rem; font-weight: 700; }
+  .moderate-button { width: 100%; border: 0; border-radius: 999px; background: var(--moderate-button, #111827); color: white; padding: .85rem 1rem; font: inherit; font-weight: 900; cursor: pointer; }
+  .moderate-turnstile { display: flex; justify-content: center; }
+</style>
+
+<div class="moderate-page">
+  <section class="moderate-hero">
+    <div class="moderate-container">
+      <p class="moderate-eyebrow"><%= t("moderate.appeals.eyebrow", default: "Moderation") %></p>
+      <h1 class="moderate-title"><%= t("moderate.appeals.title", default: "Appeal a decision") %></h1>
+    </div>
+  </section>
+
+  <main class="moderate-main">
+    <div class="moderate-container">
+      <div class="moderate-panel">
+        <p>
+          <strong><%= t("moderate.appeals.decision", default: "Decision") %></strong>
+          <span><%= @report.id %></span>
+        </p>
+        <% if @report.appeal_deadline_at.present? %>
+          <p><%= t("moderate.appeals.deadline", default: "You can request a free internal review until %{deadline}. A person will review it.", deadline: l(@report.appeal_deadline_at, format: :long)) %></p>
+        <% end %>
+      </div>
+
+      <%= form_with model: @appeal, url: appeals_path(token: params[:token]), scope: :appeal, class: "moderate-form" do |form| %>
+        <%= form.hidden_field :source, value: @appeal.source || "notifier" %>
+
+        <div class="moderate-grid">
+          <div>
+            <%= form.label :appellant_name, t("moderate.appeals.fields.name", default: "Name"), class: "moderate-label" %>
+            <%= form.text_field :appellant_name, class: "moderate-input" %>
+          </div>
+          <div>
+            <%= form.label :appellant_email, t("moderate.appeals.fields.email", default: "Email"), class: "moderate-label" %>
+            <%= form.email_field :appellant_email, required: true, class: "moderate-input" %>
+          </div>
+        </div>
+
+        <div>
+          <%= form.label :reason, t("moderate.appeals.fields.reason", default: "Reason for appeal"), class: "moderate-label" %>
+          <%= form.text_area :reason,
+                rows: 8,
+                maxlength: Moderate::Report::MESSAGE_MAX_LENGTH,
+                required: true,
+                class: "moderate-input",
+                placeholder: t("moderate.appeals.placeholders.reason", default: "Explain why you believe the decision should be reviewed and include any useful context.") %>
+        </div>
+
+        <% if turnstile_widget_required? && respond_to?(:cloudflare_turnstile) %>
+          <div class="moderate-turnstile">
+            <%= cloudflare_turnstile_script_tag if respond_to?(:cloudflare_turnstile_script_tag) %>
+            <%= cloudflare_turnstile %>
+          </div>
+        <% end %>
+
+        <% if @appeal.errors.any? %>
+          <div class="moderate-error"><%= @appeal.errors.full_messages.to_sentence %></div>
+        <% end %>
+
+        <%= form.submit t("moderate.appeals.submit", default: "Submit appeal"), class: "moderate-button" %>
+      <% end %>
+    </div>
+  </main>
+</div>