ree_lib 1.3.13 → 1.3.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a4843ec9ab12ce886333af41c258c9994ced5666fc6720a443fd42e7b8e1300
-  data.tar.gz: de155878c3031c3bcbfc24a3ca1b2fb1cf6822420cbd3959f3221da9172f1769
+  metadata.gz: 2ecb6d379981355aad60ca8e7f67493643cc351e3f5232c2d8baa326a7630d07
+  data.tar.gz: 2530c228029eb4df4e96d6208f7a0c13c22aeb263c573e69372683f4f195449f
 SHA512:
-  metadata.gz: 399d35c7b455d605572dcf8c5ebd426de556401e9eb6fd75b0c47745abf691dc8956f743e94e3ab8674c991d6bea040d55901e0b9443d7ec55a7c7bbc609f65a
-  data.tar.gz: ecad1589e6231b1fee0baa64d7bfcc5fea36dcb23deb5b02b6bbe9f0bcc307934f50ec086b7ec795c55a8a22c899516c8680b1bb0943c50136dcb9020963914d
+  metadata.gz: b1cc7a1ffbb0a4946d8359bb24ac0340c567fe9631dd389c70dc78fba3b5812d963d7174352a0e50ea7c918e7004a2ffa9c989797673978687c7865199179eb0
+  data.tar.gz: 815c690e32475a28c02dc3bbf8b4b8808b0b23302dd0cb8e5f35322b688f26ed68f4e1d98a0c4e10a9b6d80194a5fafec15fa76d8a0e60895b394918c4446754

data/Gemfile.lock

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

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

@@ -54,11 +54,12 @@ through `ree_logger`.
 
 ## What gets audited
 
-`Route#audited?` returns `internal?` unless the route says otherwise:
+Nothing is audited until the route says so:
 
 ```ruby
 get "api/v1/admin/users" do
-  visibility :internal    # audited by default
+  visibility :internal
+  audit true              # recorded
 end
 
 get "api/v1/admin/health" do
@@ -66,19 +67,20 @@ get "api/v1/admin/health" do
   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.
+The flag is declared at the route and nowhere else. Deriving it from
+`visibility` would work just as well and read far worse: whether a call lands in
+the access trail is exactly the kind of fact a reader must see where the route
+is written, not infer from a flag that means something else.
+
+Forgetting it is not possible where it matters: like `visibility`, `audit` is
+mandatory on admin paths — a route whose path carries an `admin` segment fails
+at boot until it declares one. So the audited set cannot drift away from the set
+of routes that reach client data.
 
 ### `audit :on_annotation`
 
@@ -113,7 +115,7 @@ Annotating before the check, not after, keeps a refusal in the trail as well:
 | `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` |
+| `status` | `:ok`, `:denied`, `:not_found`, `: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 |
@@ -122,6 +124,12 @@ Annotating before the check, not after, keeps a refusal in the trail as well:
 `:permission`. A refusal to show client data is as much an audit fact as
 showing it.
 
+`:denied` and `:not_found` are split out of `:error` on purpose. A refusal by
+permission and an ordinary "there was nothing to show" are both normal outcomes;
+filing them next to a crash makes a compliance report say something broke when
+nothing did. The split follows the domain error type, so an application gets it
+without classifying anything itself.
+
 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

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

@@ -47,7 +47,7 @@ class ReeAudit::Audit
       event.status = :ok
       result
     rescue StandardError => e
-      event.status = denied?(e) ? :denied : :error
+      event.status = status_for(e)
       event.error_type = e.class.name
       event.error_message = e.message.to_s[0, MAX_ERROR_MESSAGE_LENGTH]
       raise
@@ -62,11 +62,20 @@ class ReeAudit::Audit
 
   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
+  # A refusal to show client data is as much an audit fact as showing it — and
+  # it must not be filed next to a crash. Neither must "there was nothing to
+  # show": a domain 404 is an ordinary outcome, and reading it as a failure in a
+  # compliance report tells the reader something broke when nothing did.
+  def status_for(e)
+    return :error if !e.is_a?(ReeErrors::Error)
+
+    case e.type
+    when :permission then :denied
+    when :not_found then :not_found
+    else :error
+    end
   rescue StandardError
-    false
+    :error
   end
 
   # The trail must never be the reason a request fails.

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

@@ -4,7 +4,7 @@
 # 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
+  STATUSES = [:ok, :denied, :not_found, :error].freeze
 
   attr_accessor :action_name, :package_name, :summary, :sections,
                 :request_method, :path, :request_path, :params, :accessor,

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

@@ -3,11 +3,13 @@
 package_require('ree_audit/beans/audit')
 package_require('ree_audit/event')
 package_require('ree_errors/permission_error')
+package_require('ree_errors/not_found_error')
 
 RSpec.describe :audit do
   link :audit, from: :ree_audit
   link :config, from: :ree_audit
   link :permission_error, from: :ree_errors
+  link :not_found_error, from: :ree_errors
   link :logger, from: :ree_logger
 
   # Captures what the application would have persisted.
@@ -89,6 +91,18 @@ RSpec.describe :audit do
     expect(written.error_message).to eq("not allowed")
   end
 
+  # 404 предметной области — обычный исход, а не поломка: строка «нечего
+  # показать» в отчёте соответствия не должна читаться как сбой.
+  it "records a domain not-found as its own outcome, not as a failure" do
+    klass = not_found_error(:missing)
+
+    expect {
+      audit.around(event) { raise klass.new("nothing here") }
+    }.to raise_error(klass)
+
+    expect(test_sink.events.first.status).to eq(:not_found)
+  end
+
   it "records an arbitrary failure as an error and lets it through" do
     expect {
       audit.around(event) { raise ArgumentError.new("boom") }

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

@@ -99,6 +99,14 @@ RSpec.describe "ree_routes audit" do
           summary "Internal route"
           sections "Admin"
           visibility :internal
+          audit true
+          action :ok_cmd, **opts
+        end
+
+        get "api/internal_undeclared" do
+          summary "Internal route that never mentions audit"
+          sections "Admin"
+          visibility :internal
           action :ok_cmd, **opts
         end
 
@@ -148,6 +156,7 @@ RSpec.describe "ree_routes audit" do
           summary "Internal route refusing access"
           sections "Admin"
           visibility :internal
+          audit true
           action :denied_cmd, **opts
         end
 
@@ -155,6 +164,7 @@ RSpec.describe "ree_routes audit" do
           summary "Internal route blowing up"
           sections "Admin"
           visibility :internal
+          audit true
           action :boom_cmd, **opts
         end
       end
@@ -274,6 +284,13 @@ RSpec.describe "ree_routes audit" do
     expect(event.accessor).to eq({user: "visitor"})
   end
 
+  it "leaves an internal route that never declared audit out of the trail" do
+    get "api/internal_undeclared"
+
+    expect(last_response.status).to eq(200)
+    expect(test_sink.events).to be_empty
+  end
+
   it "leaves a silenced internal route out of the trail" do
     get "api/internal_silenced"
 

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

@@ -97,6 +97,14 @@ module ReeRoutes
           )
         end
 
+        if !builder.get_route.audit_declared? && admin_path?(path)
+          raise ArgumentError.new(
+            "admin route #{path} must declare audit explicitly: " \
+            "`audit true` to record the call in the access trail, " \
+            "or `audit false` if the route touches nothing worth recording"
+          )
+        end
+
         route = builder.get_route
 
         @dsl.link(route.action.name, from: route.action.package_name)

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

@@ -16,12 +16,18 @@ 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.
+  # Auditing is declared at the route and nowhere else. Deriving it from
+  # `visibility` would work just as well and read far worse: whether a call
+  # lands in the access trail is exactly the kind of fact that must be visible
+  # where the route is written, not inferred from a flag that means something
+  # else. `audit` is mandatory on admin paths (see DSL#define_route), so the
+  # audited set still cannot drift away from the routes that touch client data.
   def audited?
-    @audit.nil? ? internal? : @audit != false
+    @audit == true || @audit == :on_annotation
+  end
+
+  def audit_declared?
+    !@audit.nil?
   end
 
   # `audit :on_annotation` — a public route that the client calls for its own

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

@@ -76,7 +76,14 @@ RSpec.describe ReeRoutes::DSL, type: [:autoclean] do
         default_warden_scope :user
 
         get "internal_default" do
-          summary "Internal route, audited by default"
+          summary "Internal route that says it is audited"
+          action :cmd, from: :ree_routes_test
+          visibility :internal
+          audit true
+        end
+
+        get "internal_undeclared" do
+          summary "Internal route that never mentions audit"
           action :cmd, from: :ree_routes_test
           visibility :internal
         end
@@ -137,7 +144,10 @@ RSpec.describe ReeRoutes::DSL, type: [:autoclean] do
     }
 
     expect(routes["internal_default"].audited?).to eq(true)
+    expect(routes["internal_undeclared"].audited?).to eq(false)
+    expect(routes["internal_undeclared"].audit_declared?).to eq(false)
     expect(routes["internal_silenced"].audited?).to eq(false)
+    expect(routes["internal_silenced"].audit_declared?).to eq(true)
     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)

data/lib/ree_lib/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ree_lib
 version: !ruby/object:Gem::Version
-  version: 1.3.13
+  version: 1.3.15
 platform: ruby
 authors:
 - Ruslan Gatiyatov