ree_lib 1.3.11 → 1.3.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49fa98abf408507fb7c59dea94efc94717156aa50e76b3015aee6dcada1e0f17
-  data.tar.gz: 9a5927b28c56d6b8982e2565340d7816600f894becd05493bfcb9178196e85c6
+  metadata.gz: 5a4843ec9ab12ce886333af41c258c9994ced5666fc6720a443fd42e7b8e1300
+  data.tar.gz: de155878c3031c3bcbfc24a3ca1b2fb1cf6822420cbd3959f3221da9172f1769
 SHA512:
-  metadata.gz: ccdc45ab27ff92239fa01fa4bdd678c29d45a102af203192991acbf12caf447b77a6a8849d6a6f23d1891453b29074e1ed1a1503f239102d0e15948d40f4b364
-  data.tar.gz: e6af57d77e1eb6c41cf5b678e216741ec505ceec40eb74abc07fbebe134d43b6e82e33e82aed2ce5fc4a1085ff730324be4678cc32d0de920b89607947902764
+  metadata.gz: 399d35c7b455d605572dcf8c5ebd426de556401e9eb6fd75b0c47745abf691dc8956f743e94e3ab8674c991d6bea040d55901e0b9443d7ec55a7c7bbc609f65a
+  data.tar.gz: ecad1589e6231b1fee0baa64d7bfcc5fea36dcb23deb5b02b6bbe9f0bcc307934f50ec086b7ec795c55a8a22c899516c8680b1bb0943c50136dcb9020963914d

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [1.3.12] - 2026-09-02
+
+- `ree_audit`: `annotate_audit` fn — the entry point product code uses to attach
+  facts to the current audited call. Declared `freeze false` so a host
+  application can stub it in its own specs.
+
 ## [1.3.11] - 2026-09-02
 
 - New `ree_audit` package: an opt-in trail of audited action calls (event,

data/Gemfile.lock

@@ -9,7 +9,7 @@ PATH
 PATH
   remote: .
   specs:
-    ree_lib (1.3.10)
+    ree_lib (1.3.13)
       bigdecimal
       binding_of_caller
       i18n

data/lib/ree_lib/packages/ree_audit/README.md

@@ -0,0 +1,202 @@
+# ree_audit
+
+An opt-in trail of audited action calls.
+
+The package answers one question: **who called what, when, and how did it end.**
+It says nothing about what happened inside the action, and nothing about files
+downloaded straight from object storage — see *Boundaries* below.
+
+## Why it exists
+
+An application that serves an internal (admin) API eventually has to answer a
+customer, an auditor or a regulator: *did your staff look at my data, and when?*
+Answering that from request logs does not work — they rotate, they contain
+secrets, and they cannot be handed to a customer. This package produces a
+structured record per audited call that an application can persist wherever it
+wants and export as-is.
+
+## Off by default
+
+`AUDIT_ENABLED` defaults to `false`, and an application that never passes
+`audit:` to the `ree_routes` plugin behaves exactly as it did before the gem was
+bumped. Both properties are covered by specs: a shared framework must not start
+recording anything because someone upgraded a dependency.
+
+When audit is disabled, `Audit#around` costs a single `if`.
+
+## Wiring it up
+
+```ruby
+class MyApp < ReeRoda::App
+  link :audit, from: :ree_audit, import: -> { Audit }
+  link :my_sink, from: :my_package, import: -> { MySink }
+
+  AUDIT = Audit.new          # singleton bean
+  AUDIT.sink = MySink.new    # the one and only mutation, at boot
+
+  plugin :ree_routes, audit: AUDIT
+end
+```
+
+A sink implements one method:
+
+```ruby
+class MySink < ReeAudit::Sink
+  def write(event)
+    # persist it
+  end
+end
+```
+
+The package ships `NullSink` (default) and `LoggerSink` (dev). A sink that
+raises never fails the request: `Audit#write_safely` catches it and reports
+through `ree_logger`.
+
+## What gets audited
+
+`Route#audited?` returns `internal?` unless the route says otherwise:
+
+```ruby
+get "api/v1/admin/users" do
+  visibility :internal    # audited by default
+end
+
+get "api/v1/admin/health" do
+  visibility :internal
+  audit false             # deliberately silent
+end
+
+get "api/v1/exports" do
+  audit true              # public route reaching into someone else's data
+end
+
+get "api/v1/organizations/:id/balance" do
+  audit :on_annotation    # the owner calls it too — see below
+end
+```
+
+Tying the default to `visibility` rather than to a hand-kept list is deliberate:
+`visibility` is mandatory on admin paths (the routes DSL fails at boot without
+it), so the audited set cannot drift away from the set of routes that actually
+touch client data.
+
+### `audit :on_annotation`
+
+Some routes are called by two different people: the owner of the data, reading
+its own, and a staff member reading someone else's. Which one it was is known
+only after the permission check has run, inside the action — so the event is
+always assembled, and it reaches the sink only if the code annotated it:
+
+```ruby
+def call(organization_id, user_id)
+  admin = platform_admins.active.by_user(user_id).first
+
+  if admin
+    # this call was made by staff, and that is what makes it worth recording
+    annotate_audit(organization_id: organization_id, staff_id: admin.id)
+  end
+  ...
+end
+```
+
+`audit true` on such a route would bury the handful of staff calls under every
+ordinary request the owners make; leaving it unaudited would lose them.
+Annotating before the check, not after, keeps a refusal in the trail as well:
+`Event#recordable?` is decided in `ensure`, when the annotation is already there.
+
+## The event
+
+| field | meaning |
+|---|---|
+| `action_name`, `package_name` | which action ran |
+| `summary`, `sections` | route metadata, useful for grouping and for classifying sensitivity |
+| `request_method`, `path`, `request_path` | `path` is the DSL template (stable), `request_path` is the actual path (shows the object) |
+| `params` | what the action received, after filtering |
+| `accessor` | the authenticated object — the application decides how to read it |
+| `status` | `:ok`, `:denied`, `:error` |
+| `error_type`, `error_message` | present when the call failed; message truncated to 512 chars |
+| `started_at`, `duration_ms` | timing (monotonic clock) |
+| `annotations` | whatever the application attached during the call |
+
+`:denied` means the action raised a `ReeErrors::Error` whose type is
+`:permission`. A refusal to show client data is as much an audit fact as
+showing it.
+
+There is **no HTTP status** on the event, and that is not an oversight: the
+wrapper sits around the action call, while Roda sets the status afterwards (and,
+on an exception, in the application's `error` block). Observing it here is
+impossible, and deriving it from the error type would put a guess into an audit
+trail. `status` carries the fact instead.
+
+## Annotations
+
+Product code attaches what only it knows:
+
+```ruby
+class MyPackage::AdminUploadQuery
+  action :admin_upload_query do
+    link :annotate_audit, from: :ree_audit
+  end
+
+  def call(access, attrs)
+    upload = find_upload(attrs)
+    annotate_audit(organization_id: upload.organization_id,
+                   subject: {type: :upload, id: upload.uuid})
+    ...
+  end
+end
+```
+
+`annotate_audit` returns `nil` when audit is off or the code was reached from
+outside an audited route, so it is always safe to call.
+
+Use the `annotate_audit` fn rather than `ReeAudit.annotate` directly. A bare
+constant works, but Ree only verifies a declared package dependency for
+`link`/`import` — so removing `depends_on :ree_audit` as "unused" would compile
+fine and blow up with `NameError` in production. With `link`, the same removal
+fails loudly at load time.
+
+## Params filtering
+
+Two limits, applied before the event reaches the sink:
+
+* keys containing any `filter_words` are replaced with `'FILTERED'` **at any
+  depth** (the logger only inspects the top level);
+* anything nested deeper than `AUDIT_MAX_PARAMS_DEPTH` becomes
+  `'[TRUNCATED_DEPTH]'`, and a payload whose JSON exceeds
+  `AUDIT_MAX_PARAMS_BYTES` is replaced with `{truncated: true, size: N}`.
+
+This is a blacklist, and it is the framework's job: it protects any host
+application from leaking a credential. An application that exports the trail to
+its customers should apply its own **whitelist** on top — a blacklist silently
+passes through a key someone adds six months from now.
+
+## Nested calls
+
+Events live on a per-fiber stack (`ReeAudit::Context`), so an audited action may
+call another one without the inner call stealing the outer one's annotations.
+The stack is unwound in `ensure`, including when the action raises — a leftover
+event would attach one client's context to the next request served by the same
+fiber.
+
+## Configuration
+
+| variable | default | meaning |
+|---|---|---|
+| `AUDIT_ENABLED` | `false` | master switch |
+| `AUDIT_MAX_PARAMS_BYTES` | `4096` | size limit for the serialized params |
+| `AUDIT_MAX_PARAMS_DEPTH` | `4` | nesting limit |
+| `AUDIT_FILTER_WORDS` | see `Config::DEFAULT_FILTER_WORDS` | comma-separated |
+
+## Boundaries
+
+The package answers *who called what*. It does not see anything that bypasses
+the application: direct database access, an object-storage console, or a file
+fetched with a pre-signed URL that was handed out earlier. An application that
+needs those answers has to record them where they happen.
+
+## Specs
+
+```
+cd ree_lib/lib/ree_lib && bundle exec ree spec ree_audit
+```

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

@@ -56,7 +56,7 @@ class ReeAudit::Audit
         (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_monotonic) * 1000
       ).round
       ReeAudit::Context.pop
-      write_safely(event)
+      write_safely(event) if event.recordable?
     end
   end
 

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

@@ -9,7 +9,7 @@ class ReeAudit::Event
   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
+                :duration_ms, :annotations, :on_annotation
 
   class << self
     # Keyword-only on purpose: callers live in another package and must not
@@ -23,7 +23,8 @@ class ReeAudit::Event
       path: nil,
       request_path: nil,
       params: {},
-      accessor: nil
+      accessor: nil,
+      on_annotation: false
     )
       event = new
 
@@ -37,6 +38,7 @@ class ReeAudit::Event
       event.params = params || {}
       event.accessor = accessor
       event.annotations = {}
+      event.on_annotation = on_annotation
 
       event
     end
@@ -47,6 +49,7 @@ class ReeAudit::Event
     @params = {}
     @annotations = {}
     @status = :ok
+    @on_annotation = false
   end
 
   def ok?
@@ -57,6 +60,14 @@ class ReeAudit::Event
     status == :denied
   end
 
+  # An `on_annotation` event is the same call seen from two sides: the client
+  # asking for its own data, and a staff member asking for the client's. Only
+  # the code that resolved the caller can tell them apart, and it says so by
+  # annotating — so an untouched event of that kind is not worth recording.
+  def recordable?
+    !on_annotation || !annotations.empty?
+  end
+
   def to_h
     {
       action_name: action_name,

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Точка входа для продуктового кода: прикрепить к текущему аудируемому вызову
+# то, что известно только внутри — какое право проверено, к чьим данным и к
+# какому объекту обратились.
+#
+# Почему fn, а не голая константа ReeAudit.annotate: одного `depends_on
+# :ree_audit` хватило бы, чтобы пакет загрузился, но проверка объявленной
+# зависимости (check_package_dependency_added) срабатывает только для
+# `link`/`import`. Голая константа проходит мимо неё — и удаление `depends_on`
+# как «неиспользуемого» уронило бы приложение NameError'ом уже в проде.
+class ReeAudit::AnnotateAudit
+  include Ree::FnDSL
+
+  fn :annotate_audit do
+    # fn из общего пакета иначе не подменить в спеках приложения
+    freeze false
+  end
+
+  doc("Прикрепляет факты приложения к текущему событию аудита. nil — если аудит выключен или вызов пришёл не из аудируемого маршрута.")
+  contract(Ksplat[RestKeys => Any] => Nilor[Hash])
+  def call(**attrs)
+    ReeAudit.annotate(**attrs)
+  end
+end

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

@@ -158,4 +158,41 @@ RSpec.describe :audit do
   it "ignores an annotation made outside an audited call" do
     expect(ReeAudit.annotate(permission: :access_uploads)).to be_nil
   end
+
+  context "an :on_annotation event" do
+    let(:event) {
+      ReeAudit::Event.build(action_name: :balance_query, on_annotation: true)
+    }
+
+    it "drops the call nobody annotated" do
+      result = audit.around(event) { :action_result }
+
+      expect(result).to eq(:action_result)
+      expect(test_sink.events).to be_empty
+    end
+
+    it "writes the call the action annotated" do
+      audit.around(event) do
+        ReeAudit.annotate(platform_admin_id: 7)
+        :action_result
+      end
+
+      expect(test_sink.events.size).to eq(1)
+      expect(test_sink.events.first.annotations).to eq({platform_admin_id: 7})
+    end
+
+    it "writes a refusal that was annotated before the raise" do
+      klass = permission_error(:no_access)
+
+      expect {
+        audit.around(event) do
+          ReeAudit.annotate(platform_admin_id: 7)
+          raise klass.new("not allowed")
+        end
+      }.to raise_error(klass)
+
+      expect(test_sink.events.size).to eq(1)
+      expect(test_sink.events.first.status).to eq(:denied)
+    end
+  end
 end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+package_require('ree_audit/functions/annotate_audit')
+package_require('ree_audit/event')
+
+RSpec.describe :annotate_audit do
+  link :annotate_audit, from: :ree_audit
+
+  before { ReeAudit::Context.clear }
+  after { ReeAudit::Context.clear }
+
+  it "returns nil outside an audited call" do
+    expect(annotate_audit(permission: :access_uploads)).to be_nil
+  end
+
+  it "merges into the current event" do
+    event = ReeAudit::Event.build(action_name: :some_query)
+    ReeAudit::Context.push(event)
+
+    annotate_audit(permission: :access_uploads)
+    annotate_audit(subject: {type: :upload, id: "abc"})
+
+    expect(event.annotations).to eq({
+      permission: :access_uploads,
+      subject: {type: :upload, id: "abc"}
+    })
+  end
+end

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

@@ -146,7 +146,8 @@ class Roda
                       path: route.path,
                       request_path: r.path,
                       params: filtered_params,
-                      accessor: accessor
+                      accessor: accessor,
+                      on_annotation: route.audit_on_annotation?
                     )
 
                     audit.around(audit_event) do

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

@@ -49,6 +49,34 @@ RSpec.describe "ree_routes audit" do
       end
     end
 
+    # Клиентская ручка глазами сотрудника: код опознаёт служебное обращение и
+    # помечает его аннотацией.
+    class ReeRodaAuditTest::StaffCmd
+      include ReeActions::DSL
+
+      action :staff_cmd
+
+      def call(access, attrs)
+        ReeAudit.annotate(staff_id: 42)
+        {result: "ok"}
+      end
+    end
+
+    class ReeRodaAuditTest::DeniedStaffCmd
+      include ReeActions::DSL
+
+      action :denied_staff_cmd do
+        link :permission_error, from: :ree_errors
+      end
+
+      PermissionErr = permission_error(:no_access, msg: "not allowed")
+
+      def call(access, attrs)
+        ReeAudit.annotate(staff_id: 42)
+        raise PermissionErr
+      end
+    end
+
     class ReeRodaAuditTest::BoomCmd
       include ReeActions::DSL
 
@@ -95,6 +123,27 @@ RSpec.describe "ree_routes audit" do
           action :ok_cmd, **opts
         end
 
+        get "api/on_annotation_client" do
+          summary "Client reading its own data"
+          sections "Public"
+          audit :on_annotation
+          action :ok_cmd, **opts
+        end
+
+        get "api/on_annotation_staff" do
+          summary "Staff reading someone else's data"
+          sections "Public"
+          audit :on_annotation
+          action :staff_cmd, **opts
+        end
+
+        get "api/on_annotation_staff_denied" do
+          summary "Staff refused someone else's data"
+          sections "Public"
+          audit :on_annotation
+          action :denied_staff_cmd, **opts
+        end
+
         get "api/internal_denied" do
           summary "Internal route refusing access"
           sections "Admin"
@@ -247,6 +296,31 @@ RSpec.describe "ree_routes audit" do
     expect(test_sink.events.first.status).to eq(:ok)
   end
 
+  it "leaves an unannotated :on_annotation route out of the trail" do
+    get "api/on_annotation_client"
+
+    expect(last_response.status).to eq(200)
+    expect(test_sink.events).to be_empty
+  end
+
+  it "writes an :on_annotation route once the action annotated it" do
+    get "api/on_annotation_staff"
+
+    expect(last_response.status).to eq(200)
+    expect(test_sink.events.size).to eq(1)
+    expect(test_sink.events.first.annotations).to eq({staff_id: 42})
+  end
+
+  # Отказ сотруднику — такой же факт журнала, как и показ данных: аннотация
+  # успевает лечь до того, как действие бросит исключение.
+  it "writes an annotated :on_annotation route that ended in a refusal" do
+    get "api/on_annotation_staff_denied"
+
+    expect(last_response.status).to eq(403)
+    expect(test_sink.events.size).to eq(1)
+    expect(test_sink.events.first.status).to eq(:denied)
+  end
+
   it "records a refusal and still answers 403" do
     get "api/internal_denied"
 

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

@@ -21,7 +21,16 @@ class ReeRoutes::Route
   # 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
+    @audit.nil? ? internal? : @audit != false
+  end
+
+  # `audit :on_annotation` — a public route that the client calls for its own
+  # data and a staff member calls for someone else's. The event is always
+  # assembled, but it only reaches the sink if the code annotated the call;
+  # auditing such a route unconditionally would bury the staff access under
+  # every ordinary client request.
+  def audit_on_annotation?
+    @audit == :on_annotation
   end
 
   def valid?

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

@@ -6,6 +6,7 @@ class ReeRoutes::RouteBuilder
   Redirect = Struct.new(:path, :code)
 
   VISIBILITIES = [:public, :internal].freeze
+  AUDIT_MODES = [true, false, :on_annotation].freeze
 
   def initialize
     @route = ReeRoutes::Route.new
@@ -44,10 +45,18 @@ 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
+  # Needed in exactly three cases: silencing a noisy internal route, turning
+  # the trail on for a public route that reaches into someone else's data, and
+  # `:on_annotation` for a route both the owner of the data and a staff member
+  # can call — see Route#audit_on_annotation?.
+  contract Or[Bool, Symbol] => Or[Bool, Symbol]
   def audit(value)
+    if !AUDIT_MODES.include?(value)
+      raise ArgumentError.new(
+        "audit should be one of #{AUDIT_MODES.inspect}, got #{value.inspect}"
+      )
+    end
+
     @route.audit = value
   end
 

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

@@ -98,6 +98,12 @@ RSpec.describe ReeRoutes::DSL, type: [:autoclean] do
           action :cmd, from: :ree_routes_test
           audit true
         end
+
+        get "public_on_annotation" do
+          summary "Public route the owner and a staff member both call"
+          action :cmd, from: :ree_routes_test
+          audit :on_annotation
+        end
       end
     end
   end
@@ -134,5 +140,16 @@ RSpec.describe ReeRoutes::DSL, type: [:autoclean] do
     expect(routes["internal_silenced"].audited?).to eq(false)
     expect(routes["public_default"].audited?).to eq(false)
     expect(routes["public_audited"].audited?).to eq(true)
+    expect(routes["public_on_annotation"].audited?).to eq(true)
+
+    expect(routes["internal_default"].audit_on_annotation?).to eq(false)
+    expect(routes["public_audited"].audit_on_annotation?).to eq(false)
+    expect(routes["public_on_annotation"].audit_on_annotation?).to eq(true)
   }
+
+  it "refuses an audit mode it does not know" do
+    expect {
+      ReeRoutes::RouteBuilder.new.audit(:on_annotations)
+    }.to raise_error(ArgumentError, /audit should be one of/)
+  end
 end

data/lib/ree_lib/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ree_lib
 version: !ruby/object:Gem::Version
-  version: 1.3.11
+  version: 1.3.13
 platform: ruby
 authors:
 - Ruslan Gatiyatov
@@ -277,17 +277,20 @@ files:
 - 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/README.md
 - 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/annotate_audit.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/annotate_audit_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