ree_lib 1.3.10 → 1.3.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9602630839840f13c5b0be8226aea07ddabc2846b22ee90be4d2a2ba64e43aba
-  data.tar.gz: 3bb721b4ccecb67d709d850ca7e56357fe52350a96a1b817d33654a2eed6e759
+  metadata.gz: 49fa98abf408507fb7c59dea94efc94717156aa50e76b3015aee6dcada1e0f17
+  data.tar.gz: 9a5927b28c56d6b8982e2565340d7816600f894becd05493bfcb9178196e85c6
 SHA512:
-  metadata.gz: 8afde36de03a451291b092d3449438de32ccd1f3bd5ea1356d1b487e0a91373e3ce9f7a1bd149913c26953274009244ca343c7e1a508aaab2f219b3391a3f190
-  data.tar.gz: b97d9425262c5c99d56c7d23c7069901676594060c40d93c57a9e07a846486bff0cf176c0d39fcff6f77edbdfa239af46261800a7eff74ccb964d2363bc2262d
+  metadata.gz: ccdc45ab27ff92239fa01fa4bdd678c29d45a102af203192991acbf12caf447b77a6a8849d6a6f23d1891453b29074e1ed1a1503f239102d0e15948d40f4b364
+  data.tar.gz: e6af57d77e1eb6c41cf5b678e216741ec505ceec40eb74abc07fbebe134d43b6e82e33e82aed2ce5fc4a1085ff730324be4678cc32d0de920b89607947902764

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## [Unreleased]
 
+## [1.3.11] - 2026-09-02
+
+- New `ree_audit` package: an opt-in trail of audited action calls (event,
+  per-fiber context with `ReeAudit.annotate`, recursive params filter, sinks).
+  Disabled by default via `AUDIT_ENABLED`.
+- `ree_routes`: `Route#audited?` and the `audit true/false` route DSL. Internal
+  routes are audited by default; public ones are not.
+- `ree_routes`: `Route` got the missing `before` and `redirect` accessors —
+  `RouteBuilder#before` and `#redirect` wrote to setters that did not exist.
+- `ree_roda`: the `ree_routes` plugin accepts `audit:`. Without the option the
+  plugin behaves exactly as before.
+
 ## [1.3.0] - 2025-05-14
 
 - Forward compatibility fixes for ruby 3.4

data/lib/ree_lib/Packages.schema.json

@@ -10,6 +10,10 @@
       "name": "ree_array",
       "entry_path": "packages/ree_array/package/ree_array.rb"
     },
+    {
+      "name": "ree_audit",
+      "entry_path": "packages/ree_audit/package/ree_audit.rb"
+    },
     {
       "name": "ree_dao",
       "entry_path": "packages/ree_dao/package/ree_dao.rb"

data/lib/ree_lib/packages/ree_audit/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/lib/ree_lib/packages/ree_audit/package/ree_audit/beans/audit.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+class ReeAudit::Audit
+  include Ree::BeanDSL
+
+  bean :audit do
+    singleton
+
+    # The sink is injected once, at application boot: the package ships a null
+    # sink and the host application swaps in its own. That single assignment is
+    # the only mutation this object ever sees, so it must not be frozen.
+    freeze false
+
+    link :config
+    link :filter_params
+    link :logger, from: :ree_logger
+    link 'ree_audit/sinks/null_sink', -> { NullSink }
+  end
+
+  MAX_ERROR_MESSAGE_LENGTH = 512
+
+  def sink
+    @sink ||= NullSink.new
+  end
+
+  def sink=(value)
+    @sink = value
+  end
+
+  # Wraps one action call. Everything the trail needs that is only knowable
+  # here — how it ended, how long it took, what the code annotated on the way —
+  # is filled in around the yield.
+  #
+  # The exception itself is never swallowed: an audited route must behave
+  # exactly like an unaudited one.
+  def around(event)
+    return yield if !config.enabled
+
+    event.params = filter_params(event.params || {})
+    event.started_at = Time.now
+    started_monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    ReeAudit::Context.push(event)
+
+    begin
+      result = yield
+      event.status = :ok
+      result
+    rescue StandardError => e
+      event.status = denied?(e) ? :denied : :error
+      event.error_type = e.class.name
+      event.error_message = e.message.to_s[0, MAX_ERROR_MESSAGE_LENGTH]
+      raise
+    ensure
+      event.duration_ms = (
+        (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_monotonic) * 1000
+      ).round
+      ReeAudit::Context.pop
+      write_safely(event)
+    end
+  end
+
+  private
+
+  # A refusal to show client data is as much an audit fact as showing it.
+  def denied?(e)
+    e.is_a?(ReeErrors::Error) && e.type == :permission
+  rescue StandardError
+    false
+  end
+
+  # The trail must never be the reason a request fails.
+  def write_safely(event)
+    sink.write(event)
+  rescue StandardError => e
+    logger.error(
+      "audit sink failed for #{event.action_name}",
+      {action_name: event.action_name, status: event.status},
+      e
+    )
+    nil
+  end
+end

data/lib/ree_lib/packages/ree_audit/package/ree_audit/config.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+class ReeAudit::Config
+  include Ree::BeanDSL
+
+  bean :config do
+    singleton
+    factory :build
+
+    link :to_obj, from: :ree_object
+    link :is_blank, from: :ree_object
+  end
+
+  MAX_PARAMS_BYTES = 4096
+  MAX_PARAMS_DEPTH = 4
+
+  # Blacklist of the framework layer: it protects any host application from
+  # leaking a credential into the audit trail. Applications are expected to add
+  # their own whitelist on top of it inside their sink.
+  DEFAULT_FILTER_WORDS = %w[
+    password token credential bearer authorization secret key code email phone
+  ].freeze
+
+  def build
+    to_obj({
+      enabled: parse_bool_string(ENV['AUDIT_ENABLED']),
+      max_params_bytes: get_int_value('AUDIT_MAX_PARAMS_BYTES', MAX_PARAMS_BYTES),
+      max_params_depth: get_int_value('AUDIT_MAX_PARAMS_DEPTH', MAX_PARAMS_DEPTH),
+      filter_words: parse_filter_words(ENV['AUDIT_FILTER_WORDS'])
+    })
+  end
+
+  private
+
+  def get_int_value(name, default)
+    value = ENV[name]
+
+    v = if is_blank(value)
+      default
+    else
+      Integer(value)
+    end
+
+    if v <= 0
+      raise ArgumentError, "ENV['#{name}'] should be > 0"
+    end
+
+    v
+  end
+
+  # Audit is opt-in: a host application that knows nothing about this package
+  # must not start writing an audit trail after a gem bump.
+  def parse_bool_string(bool)
+    return false if is_blank(bool)
+    bool.to_s.downcase == "true"
+  end
+
+  def parse_filter_words(value)
+    return DEFAULT_FILTER_WORDS if is_blank(value)
+    value.to_s.split(",").map { _1.strip.downcase }.reject(&:empty?)
+  end
+end

data/lib/ree_lib/packages/ree_audit/package/ree_audit/context.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Per-fiber stack of audited events.
+#
+# A stack rather than a single slot: an action is allowed to call another
+# audited action, and the inner one must not steal the outer one's annotations.
+#
+# Thread.current[] is fiber-local in Ruby, so this is safe under Falcon as well;
+# ree_datetime/functions/set_default_time_zone.rb relies on the same property.
+module ReeAudit
+  module Context
+    KEY = :ree_audit_events
+
+    class << self
+      def push(event)
+        stack << event
+        event
+      end
+
+      def pop
+        stack.pop
+      end
+
+      def current
+        stack.last
+      end
+
+      def stack
+        Thread.current[KEY] ||= []
+      end
+
+      # Leaving a stale event behind leaks one client's context into the next
+      # request served by the same fiber, so the stack is always cleaned up.
+      def clear
+        Thread.current[KEY] = []
+        nil
+      end
+
+      def empty?
+        stack.empty?
+      end
+    end
+  end
+end

data/lib/ree_lib/packages/ree_audit/package/ree_audit/event.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# One audited action call. Built by the transport layer (the ree_roda plugin),
+# enriched by the application through ReeAudit.annotate, and handed to a sink
+# once the call is over.
+class ReeAudit::Event
+  STATUSES = [:ok, :denied, :error].freeze
+
+  attr_accessor :action_name, :package_name, :summary, :sections,
+                :request_method, :path, :request_path, :params, :accessor,
+                :status, :error_type, :error_message, :started_at,
+                :duration_ms, :annotations
+
+  class << self
+    # Keyword-only on purpose: callers live in another package and must not
+    # depend on the order of the fields here.
+    def build(
+      action_name:,
+      package_name: nil,
+      summary: nil,
+      sections: [],
+      request_method: nil,
+      path: nil,
+      request_path: nil,
+      params: {},
+      accessor: nil
+    )
+      event = new
+
+      event.action_name = action_name
+      event.package_name = package_name
+      event.summary = summary
+      event.sections = sections || []
+      event.request_method = request_method
+      event.path = path
+      event.request_path = request_path
+      event.params = params || {}
+      event.accessor = accessor
+      event.annotations = {}
+
+      event
+    end
+  end
+
+  def initialize
+    @sections = []
+    @params = {}
+    @annotations = {}
+    @status = :ok
+  end
+
+  def ok?
+    status == :ok
+  end
+
+  def denied?
+    status == :denied
+  end
+
+  def to_h
+    {
+      action_name: action_name,
+      package_name: package_name,
+      summary: summary,
+      sections: sections,
+      request_method: request_method,
+      path: path,
+      request_path: request_path,
+      params: params,
+      status: status,
+      error_type: error_type,
+      error_message: error_message,
+      started_at: started_at,
+      duration_ms: duration_ms,
+      annotations: annotations
+    }
+  end
+end

data/lib/ree_lib/packages/ree_audit/package/ree_audit/functions/filter_params.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "json"
+
+class ReeAudit::FilterParams
+  include Ree::FnDSL
+
+  fn :filter_params do
+    link :config
+  end
+
+  FILTERED = 'FILTERED'
+  TRUNCATED_DEPTH = '[TRUNCATED_DEPTH]'
+
+  doc(<<~DOC)
+    Strips secrets out of request params before they reach an audit sink.
+
+    Unlike the logger filter, which only looks at top level keys, this one walks
+    the whole structure: a token nested three levels deep is still a token.
+    Two more limits keep a single event from becoming a payload dump — maximum
+    nesting depth and maximum serialized size.
+  DOC
+  contract(Hash => Hash)
+  def call(params)
+    filtered = filter_value(
+      params, 1, config.filter_words, config.max_params_depth
+    )
+
+    limit_size(filtered, config.max_params_bytes)
+  end
+
+  private
+
+  def filter_value(value, depth, filter_words, max_depth)
+    case value
+    when Hash
+      return TRUNCATED_DEPTH if depth > max_depth
+
+      value.each_with_object({}) do |(key, nested), result|
+        result[key] = if filtered_key?(key, filter_words)
+          FILTERED
+        else
+          filter_value(nested, depth + 1, filter_words, max_depth)
+        end
+      end
+    when Array
+      return TRUNCATED_DEPTH if depth > max_depth
+
+      value.map { filter_value(_1, depth + 1, filter_words, max_depth) }
+    else
+      value
+    end
+  end
+
+  def filtered_key?(key, filter_words)
+    name = key.to_s.downcase
+    filter_words.any? { name.include?(_1) }
+  end
+
+  def limit_size(params, max_bytes)
+    size = json_bytesize(params)
+
+    return params if size.nil? || size <= max_bytes
+
+    { truncated: true, size: size }
+  end
+
+  # A payload we cannot serialize is a payload we cannot measure; dropping the
+  # size limit is better than dropping the whole request.
+  def json_bytesize(params)
+    JSON.generate(params).bytesize
+  rescue StandardError
+    nil
+  end
+end

data/lib/ree_lib/packages/ree_audit/package/ree_audit/sinks/logger_sink.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "sink"
+
+# Development sink: dumps the event into the application log. Debug level on
+# purpose — an audited call is written on every admin request.
+class ReeAudit::LoggerSink < ReeAudit::Sink
+  def initialize(logger)
+    @logger = logger
+  end
+
+  def write(event)
+    @logger.debug("audit: #{event.action_name}", event.to_h)
+  end
+end

data/lib/ree_lib/packages/ree_audit/package/ree_audit/sinks/null_sink.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "sink"
+
+# Default sink: an application that never configured one gets no audit trail
+# rather than an exception.
+class ReeAudit::NullSink < ReeAudit::Sink
+  def write(event)
+    nil
+  end
+end

data/lib/ree_lib/packages/ree_audit/package/ree_audit/sinks/sink.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Destination of finished audit events. A host application implements one and
+# hands it to the ree_roda plugin; the package itself never knows where the
+# trail is stored.
+class ReeAudit::Sink
+  def write(event)
+    raise NotImplementedError, "should be implemented in derived class"
+  end
+end

data/lib/ree_lib/packages/ree_audit/package/ree_audit.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ReeAudit
+  include Ree::PackageDSL
+
+  package do
+    depends_on :ree_object
+    depends_on :ree_hash
+    depends_on :ree_datetime
+    depends_on :ree_logger
+    depends_on :ree_errors
+
+    env_var 'AUDIT_ENABLED'
+    env_var 'AUDIT_MAX_PARAMS_BYTES'
+    env_var 'AUDIT_MAX_PARAMS_DEPTH'
+    env_var 'AUDIT_FILTER_WORDS'
+  end
+
+  class << self
+    # Attaches application-level facts to the call currently being audited:
+    # which permission was checked, which object was opened, whose data it is.
+    #
+    # Returns nil when there is nothing to annotate — audit is disabled, or the
+    # code was reached from outside an audited route. Product code calls this
+    # through the `annotate_audit` fn, never through the constant directly, so
+    # that removing `depends_on :ree_audit` fails loudly instead of in
+    # production.
+    def annotate(**attrs)
+      event = Context.current
+      return nil if event.nil?
+
+      event.annotations.merge!(attrs)
+    end
+  end
+end
+
+require_relative "ree_audit/context"

data/lib/ree_lib/packages/ree_audit/spec/ree_audit/beans/audit_spec.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+package_require('ree_audit/beans/audit')
+package_require('ree_audit/event')
+package_require('ree_errors/permission_error')
+
+RSpec.describe :audit do
+  link :audit, from: :ree_audit
+  link :config, from: :ree_audit
+  link :permission_error, from: :ree_errors
+  link :logger, from: :ree_logger
+
+  # Captures what the application would have persisted.
+  let(:test_sink) {
+    Class.new(ReeAudit::Sink) do
+      attr_reader :events
+
+      def initialize
+        @events = []
+      end
+
+      def write(event)
+        @events << event
+      end
+    end.new
+  }
+
+  let(:broken_sink) {
+    Class.new(ReeAudit::Sink) do
+      def write(event)
+        raise StandardError.new("sink is down")
+      end
+    end.new
+  }
+
+  let(:event) {
+    ReeAudit::Event.build(
+      action_name: :admin_users_query,
+      package_name: :accounts,
+      summary: "List users",
+      sections: ["Admin"],
+      request_method: :get,
+      path: "api/v1/accounts/admin/users",
+      request_path: "/api/v1/accounts/admin/users",
+      params: {page: 1, token: "secret"},
+      accessor: Object.new
+    )
+  }
+
+  before do
+    ReeAudit::Context.clear
+    audit.sink = test_sink
+  end
+
+  after do
+    audit.sink = ReeAudit::NullSink.new
+    ReeAudit::Context.clear
+  end
+
+  it "writes a successful call and returns the action result" do
+    result = audit.around(event) { :action_result }
+
+    expect(result).to eq(:action_result)
+    expect(test_sink.events.size).to eq(1)
+
+    written = test_sink.events.first
+    expect(written.status).to eq(:ok)
+    expect(written.action_name).to eq(:admin_users_query)
+    expect(written.error_type).to be_nil
+    expect(written.started_at).to be_a(Time)
+    expect(written.duration_ms).to be >= 0
+  end
+
+  it "filters secrets out of the params before they reach the sink" do
+    audit.around(event) { :ok }
+
+    expect(test_sink.events.first.params).to eq({page: 1, token: 'FILTERED'})
+  end
+
+  it "records a permission refusal and lets the error through" do
+    klass = permission_error(:no_access)
+
+    expect {
+      audit.around(event) { raise klass.new("not allowed") }
+    }.to raise_error(klass, "not allowed")
+
+    written = test_sink.events.first
+    expect(written.status).to eq(:denied)
+    expect(written.error_message).to eq("not allowed")
+  end
+
+  it "records an arbitrary failure as an error and lets it through" do
+    expect {
+      audit.around(event) { raise ArgumentError.new("boom") }
+    }.to raise_error(ArgumentError, "boom")
+
+    written = test_sink.events.first
+    expect(written.status).to eq(:error)
+    expect(written.error_type).to eq("ArgumentError")
+    expect(written.error_message).to eq("boom")
+  end
+
+  it "survives a broken sink: the request completes, the failure is logged" do
+    audit.sink = broken_sink
+
+    expect(logger).to receive(:error).at_least(:once)
+
+    expect(audit.around(event) { :action_result }).to eq(:action_result)
+  end
+
+  it "keeps nested calls on a stack" do
+    inner_event = ReeAudit::Event.build(action_name: :inner_query)
+    seen = []
+
+    audit.around(event) do
+      seen << ReeAudit::Context.current.action_name
+
+      audit.around(inner_event) do
+        seen << ReeAudit::Context.current.action_name
+        :inner
+      end
+
+      seen << ReeAudit::Context.current.action_name
+      :outer
+    end
+
+    expect(seen).to eq([:admin_users_query, :inner_query, :admin_users_query])
+    expect(ReeAudit::Context.current).to be_nil
+    expect(test_sink.events.map(&:action_name)).to eq([:inner_query, :admin_users_query])
+  end
+
+  it "costs nothing when audit is disabled" do
+    allow(config).to receive(:enabled).and_return(false)
+
+    result = audit.around(event) {
+      expect(ReeAudit::Context.current).to be_nil
+      :action_result
+    }
+
+    expect(result).to eq(:action_result)
+    expect(test_sink.events).to be_empty
+  end
+
+  it "annotates the event from inside the call" do
+    audit.around(event) do
+      ReeAudit.annotate(permission: :access_uploads, organization_id: 42)
+      ReeAudit.annotate(subject: {type: :upload, id: "abc"})
+      :ok
+    end
+
+    expect(test_sink.events.first.annotations).to eq({
+      permission: :access_uploads,
+      organization_id: 42,
+      subject: {type: :upload, id: "abc"}
+    })
+  end
+
+  it "ignores an annotation made outside an audited call" do
+    expect(ReeAudit.annotate(permission: :access_uploads)).to be_nil
+  end
+end

data/lib/ree_lib/packages/ree_audit/spec/ree_audit/context_spec.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+package_require('ree_audit/event')
+
+RSpec.describe ReeAudit::Context do
+  let(:event) { ReeAudit::Event.build(action_name: :some_query) }
+
+  before { ReeAudit::Context.clear }
+  after { ReeAudit::Context.clear }
+
+  it "is empty by default" do
+    expect(ReeAudit::Context.current).to be_nil
+    expect(ReeAudit::Context).to be_empty
+  end
+
+  it "pushes and pops" do
+    ReeAudit::Context.push(event)
+    expect(ReeAudit::Context.current).to eq(event)
+
+    expect(ReeAudit::Context.pop).to eq(event)
+    expect(ReeAudit::Context.current).to be_nil
+  end
+
+  # A leftover event would be picked up by the next request served by the same
+  # fiber — one client's annotations landing on another client's trail.
+  it "is unwound even when the wrapped call raises" do
+    expect {
+      begin
+        ReeAudit::Context.push(event)
+        raise ArgumentError.new("boom")
+      ensure
+        ReeAudit::Context.pop
+      end
+    }.to raise_error(ArgumentError)
+
+    expect(ReeAudit::Context.current).to be_nil
+  end
+
+  it "keeps stacks of different threads apart" do
+    ReeAudit::Context.push(event)
+
+    other = Thread.new { ReeAudit::Context.current }.value
+
+    expect(other).to be_nil
+    expect(ReeAudit::Context.current).to eq(event)
+  end
+end

data/lib/ree_lib/packages/ree_audit/spec/ree_audit/functions/filter_params_spec.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+package_require('ree_audit/functions/filter_params')
+
+RSpec.describe :filter_params do
+  link :filter_params, from: :ree_audit
+
+  it "leaves a plain payload untouched" do
+    expect(filter_params({page: 1, per_page: 25})).to eq({page: 1, per_page: 25})
+  end
+
+  it "filters a secret sitting at the top level" do
+    expect(filter_params({password: "hunter2", page: 1})).to eq(
+      {password: 'FILTERED', page: 1}
+    )
+  end
+
+  it "filters a secret nested three levels deep" do
+    result = filter_params({user: {profile: {user_password: "hunter2", name: "Ann"}}})
+
+    expect(result).to eq(
+      {user: {profile: {user_password: 'FILTERED', name: "Ann"}}}
+    )
+  end
+
+  it "filters inside an array of hashes" do
+    result = filter_params({items: [{auth_token: "t"}, {name: "ok"}]})
+
+    expect(result).to eq({items: [{auth_token: 'FILTERED'}, {name: "ok"}]})
+  end
+
+  it "matches filter words on string keys as well" do
+    expect(filter_params({"Authorization" => "Bearer x"})).to eq(
+      {"Authorization" => 'FILTERED'}
+    )
+  end
+
+  it "cuts everything deeper than the configured depth" do
+    result = filter_params({a: {b: {c: {d: {e: 1}}}}})
+
+    expect(result).to eq({a: {b: {c: {d: '[TRUNCATED_DEPTH]'}}}})
+  end
+
+  it "replaces an oversized payload with its size" do
+    result = filter_params({blob: "x" * 5000})
+
+    expect(result[:truncated]).to eq(true)
+    expect(result[:size]).to be > 4096
+    expect(result[:blob]).to be_nil
+  end
+
+  it "keeps a payload that fits the size limit" do
+    result = filter_params({blob: "x" * 100})
+
+    expect(result[:truncated]).to be_nil
+    expect(result[:blob]).to eq("x" * 100)
+  end
+end

data/lib/ree_lib/packages/ree_audit/spec/spec_helper.rb

@@ -0,0 +1,13 @@
+RSpec.configure do |config|
+  config.extend Ree::RSpecLinkDSL
+end
+
+ENV['AUDIT_ENABLED'] = 'true'
+ENV['AUDIT_MAX_PARAMS_BYTES'] = '4096'
+ENV['AUDIT_MAX_PARAMS_DEPTH'] = '4'
+
+# The audit bean links a logger; keep it silent — the specs assert on the
+# logger object itself, not on its output.
+ENV['LOG_FILE_PATH'] = '/tmp/ree_audit.log'
+ENV['LOG_LEVEL_FILE'] = ''
+ENV['LOG_LEVEL_STDOUT'] = ''

data/lib/ree_lib/packages/ree_roda/package/ree_roda/plugins/ree_routes.rb

@@ -7,12 +7,16 @@ class Roda
         package_require("ree_json/functions/to_json")
         package_require("ree_hash/functions/transform_values")
         package_require("ree_object/functions/not_blank")
+        package_require("ree_audit/beans/audit")
+        package_require("ree_audit/event")
 
         app.plugin :all_verbs
       end
 
       def self.configure(app, opts = {})
         app.opts[:ree_routes_before] = opts[:before] if opts[:before]
+        # An application that passes no `audit:` behaves exactly as before.
+        app.opts[:ree_routes_audit] = opts[:audit] if opts[:audit]
       end
 
       module ClassMethods
@@ -126,7 +130,31 @@ class Roda
                   end
 
                   accessor = authenticated_user
-                  action_result = get_cached_action(route).call(accessor, filtered_params)
+                  audit = context.opts[:ree_routes_audit]
+
+                  action_result = if audit && route.audited?
+                    # The event carries the params exactly as the action
+                    # received them. IP, user agent and session come from the
+                    # accessor rather than from the request, so that the audit
+                    # package stays free of any Roda dependency.
+                    audit_event = ReeAudit::Event.build(
+                      action_name: route.action.name,
+                      package_name: route.action.package_name,
+                      summary: route.summary,
+                      sections: route.sections,
+                      request_method: route.request_method,
+                      path: route.path,
+                      request_path: r.path,
+                      params: filtered_params,
+                      accessor: accessor
+                    )
+
+                    audit.around(audit_event) do
+                      get_cached_action(route).call(accessor, filtered_params)
+                    end
+                  else
+                    get_cached_action(route).call(accessor, filtered_params)
+                  end
 
                   if route.serializer
                     serialized_result = get_cached_serializer(route).serialize(action_result)

data/lib/ree_lib/packages/ree_roda/package/ree_roda.rb

@@ -11,6 +11,7 @@ module ReeRoda
     depends_on :ree_object
     depends_on :ree_swagger
     depends_on :ree_errors
+    depends_on :ree_audit
   end
 end
 

data/lib/ree_lib/packages/ree_roda/spec/ree_roda/plugins/ree_routes_audit_spec.rb

@@ -0,0 +1,281 @@
+require "rack/test"
+
+package_require("ree_roda/app")
+package_require("ree_actions/dsl")
+package_require("ree_routes/dsl")
+package_require("ree_roda/plugins/ree_routes")
+package_require("ree_audit/beans/audit")
+
+require "warden"
+
+RSpec.describe "ree_routes audit" do
+  include Rack::Test::Methods
+
+  link :audit, from: :ree_audit
+
+  before :all do
+    Ree.enable_irb_mode
+
+    module ReeRodaAuditTest
+      include Ree::PackageDSL
+
+      package do
+        depends_on :ree_actions
+        depends_on :ree_errors
+      end
+    end
+
+    class ReeRodaAuditTest::OkCmd
+      include ReeActions::DSL
+
+      action :ok_cmd
+
+      def call(access, attrs)
+        {result: "ok"}
+      end
+    end
+
+    class ReeRodaAuditTest::DeniedCmd
+      include ReeActions::DSL
+
+      action :denied_cmd do
+        link :permission_error, from: :ree_errors
+      end
+
+      PermissionErr = permission_error(:no_access, msg: "not allowed")
+
+      def call(access, attrs)
+        raise PermissionErr
+      end
+    end
+
+    class ReeRodaAuditTest::BoomCmd
+      include ReeActions::DSL
+
+      action :boom_cmd
+
+      def call(access, attrs)
+        raise ArgumentError.new("boom")
+      end
+    end
+
+    class ReeRodaAuditTest::Routes
+      include ReeRoutes::DSL
+
+      opts = {from: :ree_roda_audit_test}
+
+      routes :routes do
+        default_warden_scope :audit_visitor
+
+        get "api/internal_default" do
+          summary "Internal route"
+          sections "Admin"
+          visibility :internal
+          action :ok_cmd, **opts
+        end
+
+        get "api/internal_silenced" do
+          summary "Internal route we do not want in the trail"
+          sections "Admin"
+          visibility :internal
+          audit false
+          action :ok_cmd, **opts
+        end
+
+        get "api/public_default" do
+          summary "Public route"
+          sections "Public"
+          action :ok_cmd, **opts
+        end
+
+        get "api/public_audited" do
+          summary "Public route touching someone else's data"
+          sections "Public"
+          audit true
+          action :ok_cmd, **opts
+        end
+
+        get "api/internal_denied" do
+          summary "Internal route refusing access"
+          sections "Admin"
+          visibility :internal
+          action :denied_cmd, **opts
+        end
+
+        get "api/internal_boom" do
+          summary "Internal route blowing up"
+          sections "Admin"
+          visibility :internal
+          action :boom_cmd, **opts
+        end
+      end
+    end
+
+    class AuditVisitorStrategy < Warden::Strategies::Base
+      include Ree::LinkDSL
+
+      def valid?
+        true
+      end
+
+      def authenticate!
+        success!({user: "visitor"})
+      end
+    end
+
+    Warden::Strategies.add(:audit_visitor, AuditVisitorStrategy)
+
+    audit_bean = audit
+
+    # Class.new keeps `audit_bean` in scope; a `class` keyword would open a new
+    # lexical scope and lose it.
+    audited_app = Class.new(ReeRoda::App) do
+      use Warden::Manager do |config|
+        config.default_strategies :audit_visitor
+        config.default_scope = :audit_visitor
+        config.scope_defaults :audit_visitor, strategies: [:audit_visitor], store: false
+
+        config.failure_app = -> (env) {
+          [401, {"Content-Type" => "text/plain"}, ["requires authentication"]]
+        }
+      end
+
+      plugin :ree_routes, audit: audit_bean
+
+      ree_routes ReeRodaAuditTest::Routes.new, api_url: "http://some.api.url:1337"
+
+      route do |r|
+        r.ree_routes
+      end
+    end
+
+    Object.const_set(:AuditedTestApp, audited_app)
+
+    # Same routes, no `audit:` option — the regression guard for every other
+    # project running on ree_lib.
+    plain_app = Class.new(ReeRoda::App) do
+      use Warden::Manager do |config|
+        config.default_strategies :audit_visitor
+        config.default_scope = :audit_visitor
+        config.scope_defaults :audit_visitor, strategies: [:audit_visitor], store: false
+
+        config.failure_app = -> (env) {
+          [401, {"Content-Type" => "text/plain"}, ["requires authentication"]]
+        }
+      end
+
+      plugin :ree_routes
+
+      ree_routes ReeRodaAuditTest::Routes.new, api_url: "http://some.api.url:1337"
+
+      route do |r|
+        r.ree_routes
+      end
+    end
+
+    Object.const_set(:PlainTestApp, plain_app)
+  end
+
+  after :all do
+    Ree.disable_irb_mode
+  end
+
+  let(:test_sink) {
+    Class.new(ReeAudit::Sink) do
+      attr_reader :events
+
+      def initialize
+        @events = []
+      end
+
+      def write(event)
+        @events << event
+      end
+    end.new
+  }
+
+  let(:app) { AuditedTestApp.app }
+
+  before {
+    audit.sink = test_sink
+    ReeAudit::Context.clear
+  }
+
+  after {
+    audit.sink = ReeAudit::NullSink.new
+    ReeAudit::Context.clear
+  }
+
+  it "writes an internal route to the trail" do
+    get "api/internal_default"
+
+    expect(last_response.status).to eq(200)
+    expect(last_response.body).to eq("{}")
+
+    expect(test_sink.events.size).to eq(1)
+
+    event = test_sink.events.first
+    expect(event.action_name).to eq(:ok_cmd)
+    expect(event.package_name).to eq(:ree_roda_audit_test)
+    expect(event.status).to eq(:ok)
+    expect(event.sections).to eq(["Admin"])
+    expect(event.request_method).to eq(:get)
+    expect(event.path).to eq("api/internal_default")
+    expect(event.request_path).to eq("/api/internal_default")
+    expect(event.accessor).to eq({user: "visitor"})
+  end
+
+  it "leaves a silenced internal route out of the trail" do
+    get "api/internal_silenced"
+
+    expect(last_response.status).to eq(200)
+    expect(test_sink.events).to be_empty
+  end
+
+  it "leaves a public route out of the trail" do
+    get "api/public_default"
+
+    expect(last_response.status).to eq(200)
+    expect(test_sink.events).to be_empty
+  end
+
+  it "writes a public route that asked to be audited" do
+    get "api/public_audited"
+
+    expect(last_response.status).to eq(200)
+    expect(test_sink.events.size).to eq(1)
+    expect(test_sink.events.first.status).to eq(:ok)
+  end
+
+  it "records a refusal and still answers 403" do
+    get "api/internal_denied"
+
+    expect(last_response.status).to eq(403)
+
+    event = test_sink.events.first
+    expect(event.status).to eq(:denied)
+    expect(event.error_message).to eq("not allowed")
+  end
+
+  it "records a failure and still lets the error handler answer 500" do
+    get "api/internal_boom"
+
+    expect(last_response.status).to eq(500)
+
+    event = test_sink.events.first
+    expect(event.status).to eq(:error)
+    expect(event.error_type).to eq("ArgumentError")
+  end
+
+  context "an application that never asked for audit" do
+    let(:app) { PlainTestApp.app }
+
+    it "behaves exactly as before" do
+      get "api/internal_default"
+
+      expect(last_response.status).to eq(200)
+      expect(last_response.body).to eq("{}")
+      expect(test_sink.events).to be_empty
+    end
+  end
+end

data/lib/ree_lib/packages/ree_roda/spec/spec_helper.rb

@@ -1,3 +1,6 @@
 RSpec.configure do |config|
   config.extend Ree::RSpecLinkDSL
 end
+
+# The audit plugin option is inert unless the package itself is enabled.
+ENV['AUDIT_ENABLED'] = 'true'

data/lib/ree_lib/packages/ree_routes/package/ree_routes/route.rb

@@ -3,7 +3,9 @@
 class ReeRoutes::Route
   attr_accessor :summary, :request_method, :serializer, :respond_to,
                 :sections, :action, :route, :warden_scopes, :path, :override,
-                :visibility
+                :visibility, :before, :redirect
+
+  attr_writer :audit
 
   # Routing always includes every route; visibility only affects generated docs.
   def public?
@@ -14,6 +16,14 @@ class ReeRoutes::Route
     !public?
   end
 
+  # Internal routes are audited unless told otherwise. `visibility` is
+  # mandatory for admin paths (see DSL#define_route), so this list can never
+  # drift away from the set of routes that actually touch client data — which a
+  # hand-maintained list of audited routes inevitably would.
+  def audited?
+    @audit.nil? ? internal? : @audit
+  end
+
   def valid?
     !action.nil? && !summary.nil? && !warden_scopes.nil? && !warden_scopes.empty?
   end

data/lib/ree_lib/packages/ree_routes/package/ree_routes/route_builder.rb

@@ -44,6 +44,13 @@ class ReeRoutes::RouteBuilder
     @route.summary = str
   end
 
+  # Needed in exactly two cases: silencing a noisy internal route, and turning
+  # the trail on for a public route that reaches into someone else's data.
+  contract Bool => Bool
+  def audit(value)
+    @route.audit = value
+  end
+
   contract Symbol => Symbol
   def visibility(value)
     if !VISIBILITIES.include?(value)

data/lib/ree_lib/packages/ree_routes/spec/ree_routes/dsl_spec.rb

@@ -68,6 +68,38 @@ RSpec.describe ReeRoutes::DSL, type: [:autoclean] do
         end
       end
     end
+
+    class ReeRoutesTest::AuditRoutes
+      include ReeRoutes::DSL
+
+      routes :audit_routes do
+        default_warden_scope :user
+
+        get "internal_default" do
+          summary "Internal route, audited by default"
+          action :cmd, from: :ree_routes_test
+          visibility :internal
+        end
+
+        get "internal_silenced" do
+          summary "Internal route, deliberately not audited"
+          action :cmd, from: :ree_routes_test
+          visibility :internal
+          audit false
+        end
+
+        get "public_default" do
+          summary "Public route, not audited"
+          action :cmd, from: :ree_routes_test
+        end
+
+        get "public_audited" do
+          summary "Public route reaching into someone else's data"
+          action :cmd, from: :ree_routes_test
+          audit true
+        end
+      end
+    end
   end
 
   after :all do
@@ -92,4 +124,15 @@ RSpec.describe ReeRoutes::DSL, type: [:autoclean] do
 
     expect(csv_route.respond_to).to eq(:csv)
   }
+
+  it {
+    routes = ReeRoutesTest::AuditRoutes.new.each_with_object({}) { |r, acc|
+      acc[r.path] = r
+    }
+
+    expect(routes["internal_default"].audited?).to eq(true)
+    expect(routes["internal_silenced"].audited?).to eq(false)
+    expect(routes["public_default"].audited?).to eq(false)
+    expect(routes["public_audited"].audited?).to eq(true)
+  }
 end

data/lib/ree_lib/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ReeLib
-  VERSION = "1.3.10"
+  VERSION = "1.3.11"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ree_lib
 version: !ruby/object:Gem::Version
-  version: 1.3.10
+  version: 1.3.11
 platform: ruby
 authors:
 - Ruslan Gatiyatov
@@ -276,6 +276,20 @@ files:
 - lib/ree_lib/packages/ree_array/spec/ree_array/functions/split_by_spec.rb
 - lib/ree_lib/packages/ree_array/spec/ree_array/functions/wrap_spec.rb
 - lib/ree_lib/packages/ree_array/spec/spec_helper.rb
+- lib/ree_lib/packages/ree_audit/.rspec
+- lib/ree_lib/packages/ree_audit/package/ree_audit.rb
+- lib/ree_lib/packages/ree_audit/package/ree_audit/beans/audit.rb
+- lib/ree_lib/packages/ree_audit/package/ree_audit/config.rb
+- lib/ree_lib/packages/ree_audit/package/ree_audit/context.rb
+- lib/ree_lib/packages/ree_audit/package/ree_audit/event.rb
+- lib/ree_lib/packages/ree_audit/package/ree_audit/functions/filter_params.rb
+- lib/ree_lib/packages/ree_audit/package/ree_audit/sinks/logger_sink.rb
+- lib/ree_lib/packages/ree_audit/package/ree_audit/sinks/null_sink.rb
+- lib/ree_lib/packages/ree_audit/package/ree_audit/sinks/sink.rb
+- lib/ree_lib/packages/ree_audit/spec/ree_audit/beans/audit_spec.rb
+- lib/ree_lib/packages/ree_audit/spec/ree_audit/context_spec.rb
+- lib/ree_lib/packages/ree_audit/spec/ree_audit/functions/filter_params_spec.rb
+- lib/ree_lib/packages/ree_audit/spec/spec_helper.rb
 - lib/ree_lib/packages/ree_dao/.gitignore
 - lib/ree_lib/packages/ree_dao/.rspec
 - lib/ree_lib/packages/ree_dao/bin/console
@@ -897,6 +911,7 @@ files:
 - lib/ree_lib/packages/ree_roda/package/ree_roda/services/status_from_error.rb
 - lib/ree_lib/packages/ree_roda/spec/ree_roda/app_spec.rb
 - lib/ree_lib/packages/ree_roda/spec/ree_roda/plugins/ree_logger_spec.rb
+- lib/ree_lib/packages/ree_roda/spec/ree_roda/plugins/ree_routes_audit_spec.rb
 - lib/ree_lib/packages/ree_roda/spec/ree_roda/services/build_routing_tree_spec.rb
 - lib/ree_lib/packages/ree_roda/spec/ree_roda/services/build_swagger_from_routes_spec.rb
 - lib/ree_lib/packages/ree_roda/spec/ree_roda/services/locales/en.yml