open-loam 0.1.0

data/lib/loam/event_stream.rb

@@ -0,0 +1,80 @@
+module Loam
+  # The real-time bridge: pushes selected Loam events to a browser over
+  # Server-Sent Events, so the admin updates live instead of polling.
+  #
+  # SECURITY POSTURE — default OFF. An event reaches a browser only if ALL hold:
+  #   * its name matches a declared Loam.broadcast_events pattern (opt-in), AND
+  #   * its tenant matches the connected tenant (isolation), AND
+  #   * its audience includes the connected actor (a payload `user_id`, if any,
+  #     is the sole recipient; no `user_id` means tenant-wide).
+  #
+  # FAN-OUT is behind a swappable broadcaster seam (Loam::EventStream.broadcaster).
+  # The default in-process broadcaster only sees events published in THIS process
+  # — fine for the single-process prototype; a multi-process deploy swaps in a
+  # Redis/SolidCable-backed broadcaster with no controller change (see
+  # docs/_foundation/overview.md).
+  module EventStream
+    class << self
+      attr_writer :broadcaster
+
+      def broadcaster
+        @broadcaster ||= InProcessBroadcaster.new
+      end
+
+      # Is this event name allowed to reach browsers at all? Empty allow-list →
+      # false, always (nothing leaks by default).
+      def broadcastable?(event_name)
+        Loam.broadcast_events.any? do |pattern|
+          next false if Loam::Overrides.disabled?(:broadcast_events, pattern) # an app can turn a default pattern off
+
+          Loam::Events.pattern_matches?(pattern, event_name)
+        end
+      end
+
+      # Should a broadcastable event reach a stream connected as (tenant, actor)?
+      def deliverable?(event_name, payload, tenant:, actor:)
+        return false unless broadcastable?(event_name)
+
+        payload = payload.symbolize_keys
+        return false unless payload[:tenant_id] == tenant&.id
+
+        recipient = payload[:user_id]
+        recipient.nil? || recipient == actor&.id
+      end
+
+      # One SSE message: an `event:` line (the Loam event name) and a `data:`
+      # line (JSON), ended by a blank line. Only small id-ish keys ride along —
+      # Loam events carry no attribute values, and this slices to a safe set as
+      # belt-and-suspenders (tenant_id is dropped; it is implied by the connection).
+      def frame(event_name, payload)
+        "event: #{event_name}\ndata: #{safe_payload(payload).to_json}\n\n"
+      end
+
+      private
+
+      def safe_payload(payload)
+        # id-ish keys only — never attribute values. percent/status ride along for
+        # the progress bar (Loam::ProgressJob); both are non-sensitive.
+        payload.symbolize_keys.slice(:id, :type, :user_id, :from, :to, :percent, :status).compact
+      end
+    end
+
+    # The default fan-out: subscribe to Loam::Events in THIS process and forward
+    # the events deliverable to (tenant, actor) to a sink. A `sink` is anything
+    # answering #call(sse_string) — the controller's is a Queue push.
+    class InProcessBroadcaster
+      # Returns an opaque handle to pass back to #unsubscribe.
+      def subscribe(tenant:, actor:, &sink)
+        Loam::Events.subscribe_all do |event_name, payload|
+          next unless Loam::EventStream.deliverable?(event_name, payload, tenant: tenant, actor: actor)
+
+          sink.call(Loam::EventStream.frame(event_name, payload))
+        end
+      end
+
+      def unsubscribe(handle)
+        ActiveSupport::Notifications.unsubscribe(handle) if handle
+      end
+    end
+  end
+end

data/lib/loam/eventful.rb

@@ -0,0 +1,45 @@
+module Loam
+  # Lifecycle events by convention. Included in every generated entity:
+  #
+  #   class Equipment < Loam::TenantRecord
+  #     include Loam::Eventful
+  #     event_domain :rental          # -> "rental.equipment.created" etc.
+  #   end
+  #
+  # Custom business events are published explicitly with Loam::Events.publish.
+  module Eventful
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :loam_event_domain, default: "app"
+      class_attribute :loam_event_entity, default: nil
+
+      after_create_commit  { publish_lifecycle_event("created") }
+      after_update_commit  { publish_lifecycle_event("updated") }
+      after_destroy_commit { publish_lifecycle_event("destroyed") }
+    end
+
+    class_methods do
+      def event_domain(domain)
+        self.loam_event_domain = domain.to_s
+      end
+
+      # The middle segment of the event name. It defaults to the model's param
+      # key, which is right for app models but awkward for namespaced ones —
+      # Loam::Comment would publish "loam.loam_comment.created" rather than
+      # "loam.comment.created".
+      def event_entity(name)
+        self.loam_event_entity = name.to_s
+      end
+    end
+
+    private
+
+    def publish_lifecycle_event(happened)
+      Loam::Events.publish(
+        "#{loam_event_domain}.#{loam_event_entity || model_name.param_key}.#{happened}",
+        { id: id, type: self.class.name }
+      )
+    end
+  end
+end

data/lib/loam/events.rb

@@ -0,0 +1,51 @@
+module Loam
+  # A thin domain event bus over ActiveSupport::Notifications.
+  #
+  # Convention: event names are `domain.thing.happened`, e.g.
+  # "billing.subscription.renewed", "rental.equipment.created".
+  # Publishing stamps the current tenant and actor onto the payload so
+  # subscribers are always tenant-aware.
+  module Events
+    NAME_FORMAT = /\A[a-z0-9_]+(\.[a-z0-9_]+){2,}\z/
+    PREFIX = "loam.event."
+
+    def self.publish(name, payload = {})
+      name = name.to_s
+      unless name.match?(NAME_FORMAT)
+        raise InvalidEventNameError, "Event name #{name.inspect} must follow `domain.thing.happened`"
+      end
+
+      ActiveSupport::Notifications.instrument(
+        PREFIX + name,
+        payload.merge(tenant_id: Loam::Current.tenant&.id, actor_id: Loam::Current.actor&.id)
+      )
+    end
+
+    # The subscription rule, in one place: a trailing dot is a domain prefix,
+    # anything else is an exact event name. Loam::WebhookEndpoint matches
+    # against this too, so a pattern means the same thing everywhere.
+    def self.pattern_matches?(pattern, event_name)
+      pattern = pattern.to_s
+      event_name = event_name.to_s
+
+      pattern.end_with?(".") ? event_name.start_with?(pattern) : event_name == pattern
+    end
+
+    # Every Loam event, whatever its domain — the empty prefix matches them
+    # all. Used by the webhook dispatcher, which decides per event which
+    # endpoints care.
+    def self.subscribe_all(&block)
+      subscribe("", &block)
+    end
+
+    # Subscribe to one event ("rental.equipment.created") or a whole domain
+    # ("rental.") — the block receives (event_name, payload).
+    def self.subscribe(name_or_prefix, &block)
+      pattern = PREFIX + name_or_prefix.to_s
+      matcher = pattern.end_with?(".") ? /\A#{Regexp.escape(pattern)}/ : pattern
+      ActiveSupport::Notifications.subscribe(matcher) do |full_name, _start, _finish, _id, payload|
+        block.call(full_name.delete_prefix(PREFIX), payload)
+      end
+    end
+  end
+end

data/lib/loam/export.rb

@@ -0,0 +1,74 @@
+require "csv"
+
+module Loam
+  # CSV export of a tenant-scoped relation, POLICY- and ENCRYPTION-aware:
+  #
+  #   Loam::Export.csv(Equipment.all, actor: current_actor)
+  #
+  # * only fields the actor's role may READ are columns (Loam::Policy#readable?);
+  # * an ENCRYPTED column is NEVER exported in the clear — its cell is
+  #   "[encrypted]" (the same redaction as the audit trail), so a bulk export can
+  #   never become a plaintext dump of PII a role shouldn't see;
+  # * declared custom fields are included (a dictionary field exports its stored
+  #   code, so the file round-trips back through Loam::Import);
+  # * tenant isolation is free — the relation is already scoped.
+  #
+  # Prototype scale: builds the CSV in memory with the stdlib CSV. A very large
+  # export would stream row-by-row through an enumerator body — the same column
+  # logic, a different sink.
+  module Export
+    REDACTED = "[encrypted]".freeze
+    # Never exported: tenant plumbing and optimistic-locking bookkeeping.
+    SKIP_COLUMNS = %w[tenant_id lock_version deleted_at].freeze
+
+    module_function
+
+    def csv(scope, actor:)
+      model = scope.klass
+      columns = exportable_columns(model, actor)
+
+      CSV.generate do |out|
+        out << columns.map { |c| c[:header] }
+        scope.find_each { |record| out << columns.map { |c| cell(record, c) } }
+      end
+    end
+
+    # The ordered column spec: readable real columns (encrypted ones kept but
+    # redacted), then declared custom fields.
+    def exportable_columns(model, actor)
+      policy = policy_for(model, actor)
+      encrypted = model.respond_to?(:loam_encrypted_attributes) ? model.loam_encrypted_attributes : []
+      # The blind-index columns behind searchable encrypted fields (e.g.
+      # email_hash) are internal HMACs — never export them either.
+      blind = model.respond_to?(:loam_searchable_encrypted_attributes) ? model.loam_searchable_encrypted_attributes.map { |a| "#{a}_hash" } : []
+
+      columns = model.column_names.reject { |c| SKIP_COLUMNS.include?(c) || blind.include?(c) || c == "custom_fields" }
+                     .select { |c| policy.readable?(c) }
+                     .map { |c| { header: c, name: c, kind: encrypted.include?(c) ? :encrypted : :column } }
+
+      if model.respond_to?(:custom_field_definitions)
+        model.custom_field_definitions.order(:name).each do |definition|
+          columns << { header: definition.name, name: definition.name, kind: :custom }
+        end
+      end
+
+      columns
+    end
+
+    def cell(record, column)
+      value = case column[:kind]
+              when :encrypted then REDACTED
+              when :custom    then (record.custom_field(column[:name]) rescue nil)
+              else record.public_send(column[:name])
+              end
+      Loam::Csv.safe(value) # neutralize CSV formula injection (=, +, -, @, tab/CR)
+    end
+
+    def policy_for(model, actor)
+      klass = "#{model.name}Policy".safe_constantize
+      # A blank instance as the record: readable? keys off the role, but the
+      # policy's custom-field checks read record.class.
+      (klass || Loam::Policy).new(actor, model.new)
+    end
+  end
+end

data/lib/loam/features.rb

@@ -0,0 +1,75 @@
+module Loam
+  # Runtime feature toggles: is a capability turned ON for this tenant right now.
+  #
+  #   Loam::Features.on?(:beta_dashboard)          # for the current tenant
+  #   Loam::Features.enable(:beta_dashboard)       # this tenant only
+  #   Loam::Features.enable(:beta_dashboard, scope: :global)  # everyone
+  #   Loam::Features.disable(:beta_dashboard)
+  #   Loam::Features.reset(:beta_dashboard)        # drop the override → default
+  #
+  # A flag gates a CAPABILITY (is this feature live for the tenant), which is
+  # orthogonal to a policy — that gates a PERSON (may this user act). The two
+  # coexist: a manager may be allowed to approve reports AND the approvals
+  # feature may be switched off for their tenant during a rollout.
+  #
+  # This is deliberately a thin wrapper over Loam::Configs: a flag is a boolean
+  # setting with the same override → global → declared-default resolution, so it
+  # reuses that store (no new table) and its per-request cache. Flags live under
+  # the reserved `features.` key prefix and get their own admin screen, because
+  # "flags" and "settings" are different mental models even sharing storage.
+  module Features
+    PREFIX = "features.".freeze
+
+    class << self
+      def on?(name)
+        !!Loam::Configs.get(key_for(name), default: default_for(name))
+      end
+
+      def off?(name)
+        !on?(name)
+      end
+
+      # Flip a flag on. scope: :tenant (default) overrides for the current tenant
+      # and requires a tenant in context; scope: :global sets the app-wide state.
+      def enable(name, scope: :tenant)
+        Loam::Configs.set(key_for(name), true, scope: scope)
+      end
+
+      def disable(name, scope: :tenant)
+        Loam::Configs.set(key_for(name), false, scope: scope)
+      end
+
+      # Drop the current tenant's override so the flag falls back to the global
+      # state / declared default.
+      def reset(name)
+        Loam::Configs.reset(key_for(name))
+      end
+
+      def overridden?(name)
+        Loam::Configs.overridden?(key_for(name))
+      end
+
+      # Every declared flag, sorted — the admin lists these whether or not a row
+      # exists yet, so a flag is visible the moment it is declared.
+      def declared
+        Loam.feature_defaults.keys.sort
+      end
+
+      def description(name)
+        Loam.feature_defaults.dig(name.to_s, :description)
+      end
+
+      # The declared-default state of a flag (false for an unknown one), used as
+      # the last resort when there is no override and no global row.
+      def default_for(name)
+        !!Loam.feature_defaults.dig(name.to_s, :default)
+      end
+
+      private
+
+      def key_for(name)
+        "#{PREFIX}#{name}"
+      end
+    end
+  end
+end

data/lib/loam/generated_key.rb

@@ -0,0 +1,37 @@
+module Loam
+  # Primary-key generation for tables whose key is not an integer.
+  #
+  # Rails leaves key generation to the database, which works for integer keys
+  # (a sequence or AUTOINCREMENT) and for uuid columns on Postgres, where
+  # create_table installs a gen_random_uuid() default. A *string* primary key
+  # has neither: the INSERT sends NULL and the row is rejected or lands with an
+  # empty key.
+  #
+  # Loam's tables follow the host app's key type (see
+  # Loam::Generators::PrimaryKeyOptions), so on a string-keyed app every Loam
+  # model needs its key generated in Ruby. Before this, hosts patched it in
+  # themselves with a global before_create on ActiveRecord::Base — a lot to ask
+  # of an app whose only deviation was not using bigints, and a hook broad
+  # enough to reach models that had nothing to do with Loam.
+  #
+  # Integer keys take the early return, so nothing changes for the default app.
+  module GeneratedKey
+    def self.included(base)
+      base.before_create :assign_loam_generated_key
+    end
+
+    private
+
+    def assign_loam_generated_key
+      key = self.class.primary_key
+      return if key.nil?             # a join table declared with id: false
+      return if self[key].present?   # the caller chose the key
+
+      column = self.class.columns_hash[key]
+      return if column.nil?
+      return if column.type == :integer   # the database generates this one
+
+      self[key] = SecureRandom.uuid
+    end
+  end
+end

data/lib/loam/import.rb

@@ -0,0 +1,168 @@
+require "csv"
+require "set"
+
+module Loam
+  # CSV import mapping engine — reusable, tenant-scoped, policy-safe.
+  #
+  #   Loam::Import.preview(csv)                       # headers + first rows for the mapping UI
+  #   Loam::Import.run(csv, model:, mapping:, actor:, # map CSV header => field
+  #                    match_key: "name",             # update-or-create by a key (nil = create-only)
+  #                    dry_run: true,                 # validate + report, commit nothing
+  #                    progress: progress_job)        # advance a Loam::ProgressJob per row
+  #
+  # Safety: the mapping may only target fields the actor's role can WRITE (real
+  # columns + declared custom fields); tenant_id, plumbing, and non-permitted
+  # fields are refused (no crafted mapping can smuggle a value past the policy).
+  # Each row is its OWN save — a bad row is logged (row number + reason) and
+  # SKIPPED, never half-committed, and the import continues. Records land in the
+  # current tenant automatically (TenantRecord). Malformed CSV is a clean error,
+  # not a crash.
+  module Import
+    PLUMBING = %w[id tenant_id created_at updated_at lock_version deleted_at custom_fields].freeze
+
+    Result = Struct.new(:created, :updated, :failed, :errors, keyword_init: true) do
+      def total = created + updated + failed
+      def to_h = { created: created, updated: updated, failed: failed, errors: errors }
+    end
+
+    module_function
+
+    # Resolve an entity_type string to a model — ONLY a Loam::TenantRecord
+    # subclass (never an arbitrary constant), so an import target can't be
+    # smuggled to a global model like User (same guard as the business-rules
+    # engine).
+    def allowed_model(entity_type)
+      klass = entity_type.to_s.safe_constantize
+      unless klass.is_a?(Class) && klass < Loam::TenantRecord
+        raise Loam::Error, "import target #{entity_type.inspect} is not a Loam entity"
+      end
+
+      klass
+    end
+
+    def preview(csv_string, limit: 5)
+      rows = safe_parse(csv_string)
+      { headers: rows.first || [], rows: rows.drop(1).first(limit) }
+    end
+
+    # The fields a mapping may target for `model` given `actor`'s role.
+    def allowed_targets(model, actor)
+      policy = policy_for(model, actor)
+      columns = (model.column_names - PLUMBING).select { |c| policy.writable?(c) }
+      customs = if model.respond_to?(:custom_field_definitions)
+                  model.custom_field_definitions.map(&:name).select { |n| policy.custom_field_writable?(n) }
+                else
+                  []
+                end
+      (columns + customs).to_set
+    end
+
+    def run(csv_string, model:, mapping:, actor:, match_key: nil, dry_run: false, progress: nil)
+      refuse_bad_mapping!(mapping, allowed_targets(model, actor))
+
+      rows = safe_parse(csv_string)
+      headers = rows.first || []
+      result = Result.new(created: 0, updated: 0, failed: 0, errors: [])
+
+      rows.drop(1).each_with_index do |row, index|
+        line = index + 2 # human row number (1-based + header)
+        begin
+          attrs = row_attributes(headers, row, mapping)
+          record, is_new = find_or_build(model, attrs, match_key)
+          assign(record, attrs, model)
+
+          if dry_run
+            raise ActiveRecord::RecordInvalid, record unless record.valid?
+          else
+            record.save!
+          end
+          is_new ? (result.created += 1) : (result.updated += 1)
+        rescue StandardError => error
+          # Store ONLY the row number + message — NEVER the raw cell values. The
+          # result is persisted (Loam::ProgressJob.result); a failed row into an
+          # encrypted field would otherwise write PLAINTEXT PII at rest.
+          result.failed += 1
+          result.errors << { "row" => line, "message" => error.message }
+        end
+        progress&.advance
+      end
+
+      result
+    end
+
+    # The failed rows as a fix-and-re-upload CSV — rebuilt from the ORIGINAL csv
+    # (a transient download the user already holds), NOT from the persisted
+    # result (which carries no cell values). Each cell is neutralized against CSV
+    # formula injection.
+    def error_csv(result, csv_string)
+      rows = safe_parse(csv_string)
+      headers = rows.first || []
+      data_rows = rows.drop(1)
+
+      CSV.generate do |out|
+        out << (Array(headers) + [ "_error" ])
+        result.errors.each do |error|
+          original = data_rows[error["row"] - 2] || [] # row is 1-based incl. the header
+          out << original.map { |cell| Loam::Csv.safe(cell) } + [ error["message"] ]
+        end
+      end
+    end
+
+    # ---- internals ----
+
+    def refuse_bad_mapping!(mapping, allowed)
+      mapping.each_value do |target|
+        next if target.to_s.blank?
+        next if allowed.include?(target.to_s)
+
+        raise Loam::Error, "import mapping refuses #{target.inspect} — not a writable column or custom field"
+      end
+    end
+
+    def row_attributes(headers, row, mapping)
+      cells = Hash[headers.zip(row)]
+      mapping.each_with_object({}) do |(header, target), attrs|
+        next if target.to_s.blank?
+
+        attrs[target.to_s] = cells[header]
+      end
+    end
+
+    def find_or_build(model, attrs, match_key)
+      key = match_key.to_s
+      if key.present? && attrs[key].present?
+        # find_by is tenant-scoped, so update-by-key can only ever hit a record
+        # in the CURRENT tenant.
+        existing = model.find_by(key => attrs[key])
+        return [ existing, false ] if existing
+      end
+      [ model.new, true ]
+    end
+
+    def assign(record, attrs, model)
+      columns = model.column_names.to_set
+      customs = model.respond_to?(:custom_field_definitions) ? model.custom_field_definitions.map(&:name).to_set : Set.new
+
+      attrs.each do |field, value|
+        if columns.include?(field)
+          record.public_send("#{field}=", value)
+        elsif customs.include?(field)
+          record.set_custom_field(field, value)
+        end
+      end
+    end
+
+    def safe_parse(csv_string)
+      CSV.parse(csv_string.to_s)
+    rescue CSV::MalformedCSVError => error
+      raise Loam::Error, "could not parse CSV: #{error.message}"
+    end
+
+    def policy_for(model, actor)
+      klass = "#{model.name}Policy".safe_constantize
+      # A blank instance as the record: readable?/writable? key off the role, but
+      # custom_field_writable? reads record.class.custom_field_definitions.
+      (klass || Loam::Policy).new(actor, model.new)
+    end
+  end
+end

data/lib/loam/inbound_webhooks.rb

@@ -0,0 +1,125 @@
+require "openssl"
+require "digest"
+
+module Loam
+  # Receiving webhooks FROM external systems (the inbound sibling of
+  # Loam::Webhooks). One entry point — `ingest` — does the whole verified,
+  # replay-resistant pipeline and returns a Result the controller turns into an
+  # HTTP status. Kept here (not in a controller) so it is testable without HTTP
+  # and shared by the generated app and the demo.
+  #
+  # THE ORDER OF CHECKS is deliberate — cheapest and least-trusting first:
+  #   1. body size      -> 413  (never HMAC a huge body)
+  #   2. token resolve  -> 404  (unknown/inactive source)
+  #   3. signature      -> 401  (constant-time HMAC over the RAW body)
+  #   4. timestamp      -> 401  (defense-in-depth; see note below)
+  #   5. dedupe         -> 200  (a replay is idempotent, not an error)
+  #   6. ingest+publish -> 202
+  #
+  # Every AUTH failure returns 401 with no distinguishing body, so a sender can't
+  # probe which check failed; the specific reason is logged server-side only.
+  #
+  # REPLAY: the real defense is the (source_id, external_id) dedupe. The timestamp
+  # window is defense-in-depth: unless the sender signs the timestamp too, a
+  # replayer can refresh an unsigned timestamp header. Don't over-trust it.
+  module InboundWebhooks
+    MAX_BYTES = 1_000_000
+
+    Result = Struct.new(:status, :reason, :delivery, keyword_init: true)
+
+    module_function
+
+    def ingest(token:, raw_body:, headers:)
+      Loam::Telemetry.span("inbound_webhook") { run_ingest(token, raw_body.to_s, headers) }
+    end
+
+    def run_ingest(token, raw_body, headers)
+      return Result.new(status: 413, reason: "body too large") if raw_body.bytesize > MAX_BYTES
+
+      source = Loam::InboundWebhookSource.resolve(token)
+      return Result.new(status: 404, reason: "unknown or inactive source") if source.nil?
+
+      signature = header(headers, source.signature_header_key)
+      return unauthorized("missing signature") if signature.blank?
+      return unauthorized("bad signature") unless valid_signature?(source.secret, raw_body, signature)
+
+      if source.timestamp_header.present?
+        return unauthorized("stale or missing timestamp") unless fresh_timestamp?(header(headers, source.timestamp_header), source.tolerance)
+      end
+
+      external_id = delivery_id(source, headers, raw_body)
+
+      begin
+        delivery = nil
+        Loam::InboundWebhookDelivery.transaction do
+          delivery = Loam::InboundWebhookDelivery.create!(
+            source: source, external_id: external_id, event_name: source.event_name,
+            status: "received", received_at: Time.current, payload: parse(raw_body)
+          )
+          # Scalar-only payload by convention (like the outbound path): the body
+          # lives on the delivery row, subscribers read it from there. Publishing
+          # inside the txn ties capture to the row — a publish failure rolls the
+          # row back so the sender's retry isn't deduped away.
+          Loam::Events.publish(source.event_name, { source_id: source.id, delivery_id: delivery.id })
+        end
+        Result.new(status: 202, reason: "accepted", delivery: delivery)
+      rescue ActiveRecord::RecordNotUnique
+        # A concurrent or replayed delivery with the same external_id — already
+        # processed. Idempotent success, NOT a second publish.
+        Result.new(status: 200, reason: "duplicate (already processed)")
+      end
+    end
+
+    # --- verification internals ---
+
+    def valid_signature?(secret, body, provided)
+      expected = "sha256=" + OpenSSL::HMAC.hexdigest("SHA256", secret.to_s, body)
+      # Hash both to a fixed 64-hex length so the compare is constant-time and
+      # never raises on an attacker-chosen length.
+      ActiveSupport::SecurityUtils.fixed_length_secure_compare(
+        Digest::SHA256.hexdigest(expected), Digest::SHA256.hexdigest(provided.to_s)
+      )
+    rescue StandardError
+      false
+    end
+
+    def fresh_timestamp?(raw, tolerance)
+      return false if raw.blank?
+
+      seconds = (Integer(raw.to_s) rescue (Time.parse(raw.to_s).to_i rescue nil))
+      return false if seconds.nil?
+
+      (Time.current.to_i - seconds).abs <= tolerance.to_i
+    end
+
+    def delivery_id(source, headers, body)
+      if source.delivery_id_header.present?
+        value = header(headers, source.delivery_id_header)
+        return value if value.present?
+      end
+      # No delivery-id header configured (or absent): fall back to a body hash.
+      # Consequence: identical bodies dedupe. A sender with a real delivery id
+      # should configure delivery_id_header so distinct-but-identical bodies pass.
+      Digest::SHA256.hexdigest(body)
+    end
+
+    def header(headers, name)
+      return nil if name.blank?
+
+      # ActionDispatch::Http::Headers is case-insensitive on []; a plain Hash
+      # (tests) is not — try the given key then a couple of common casings.
+      headers[name] || headers[name.to_s] || headers[name.to_s.downcase] ||
+        headers["HTTP_#{name.to_s.upcase.tr('-', '_')}"]
+    end
+
+    def parse(raw_body)
+      JSON.parse(raw_body)
+    rescue JSON::ParserError
+      { "raw" => raw_body }
+    end
+
+    def unauthorized(reason)
+      Result.new(status: 401, reason: reason)
+    end
+  end
+end