ree_lib 1.3.13 → 1.3.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a4843ec9ab12ce886333af41c258c9994ced5666fc6720a443fd42e7b8e1300
-  data.tar.gz: de155878c3031c3bcbfc24a3ca1b2fb1cf6822420cbd3959f3221da9172f1769
+  metadata.gz: 2ebed252b6557db13e60268884fd6b1a0f405f256d28aaf18953764886ab6cb0
+  data.tar.gz: e6328fda6013213c588f834b5a0782c271c76686b8303a0f458cfac5e926c80d
 SHA512:
-  metadata.gz: 399d35c7b455d605572dcf8c5ebd426de556401e9eb6fd75b0c47745abf691dc8956f743e94e3ab8674c991d6bea040d55901e0b9443d7ec55a7c7bbc609f65a
-  data.tar.gz: ecad1589e6231b1fee0baa64d7bfcc5fea36dcb23deb5b02b6bbe9f0bcc307934f50ec086b7ec795c55a8a22c899516c8680b1bb0943c50136dcb9020963914d
+  metadata.gz: 06ad16d1ca9361397b0e324d8ab0d9a3a064337831384f45616dd500efb88367c84be252537d203e07ec08cb109e8f976980ff39ac2de315f96938a21edc697e
+  data.tar.gz: fa3b6b910f9855585af6f0e985720db3773d7483779f65d3907badc16711e5bfdd159abcfcd8135466a5a2c57a75645da44c79ba532e0bcd9bf777d50aa7bdd5

data/Gemfile.lock

@@ -9,7 +9,7 @@ PATH
 PATH
   remote: .
   specs:
-    ree_lib (1.3.13)
+    ree_lib (1.3.14)
       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`
 

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.14"
 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.14
 platform: ruby
 authors:
 - Ruslan Gatiyatov