ree_lib 1.3.9 → 1.3.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 237cf0a00005f59af6c0741f79302159d84433b60b63e401baa4ae95ab0dd2ae
-  data.tar.gz: f9c00515a41e9d78fc2c3ac1785d5a8a21d1f4142461537299e4c1678d4a6b61
+  metadata.gz: 49fa98abf408507fb7c59dea94efc94717156aa50e76b3015aee6dcada1e0f17
+  data.tar.gz: 9a5927b28c56d6b8982e2565340d7816600f894becd05493bfcb9178196e85c6
 SHA512:
-  metadata.gz: c712530b729aa1e48d53de393ee737b7605c233108940e78f09f4561c36b69c413136880f8b72f73f694d4a6ac5ee7e4010d2d46ff2dcdb30450ad1fd2bb9a56
-  data.tar.gz: e148d3f589e0c2863a9b1958d903458407c1646f0fca6ca79c5fb0839893c0bc00059b4a80a9c0b45cf6710e4e9b6802f6a94ee9b8958fa485701164cd99a240
+  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/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ../ree
   specs:
-    ree (1.3.3)
+    ree (1.3.5)
       base64
       commander
       logger
@@ -9,7 +9,7 @@ PATH
 PATH
   remote: .
   specs:
-    ree_lib (1.3.9)
+    ree_lib (1.3.10)
       bigdecimal
       binding_of_caller
       i18n

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