rubocop-dev_doc 0.12.1 → 0.13.0

data/lib/rubocop/cop/dev_doc/auth/login_only_policy_justification.rb

@@ -0,0 +1,165 @@
+require_relative 'adjacent_justification'
+
+module RuboCop
+  module Cop
+    module DevDoc
+      module Auth
+        # A policy gate whose entire body is "is anyone signed in?" must carry
+        # an adjacent justification naming where per-record scoping happens.
+        #
+        # ## Rationale
+        # `authorize :index do user_signed_in? end` authorizes EVERY
+        # authenticated user — including users belonging to other tenants. That
+        # is only safe when something *else* scopes what the action can reach:
+        # the controller resolves records through `current_user` associations,
+        # the id in the URL is a non-enumerable capability token, or the data is
+        # genuinely public. When none of those hold — when the action resolves
+        # any record from a client-controlled param — a login-only gate IS a
+        # cross-tenant IDOR: any signed-in user can enumerate ids and read
+        # another tenant's records. This cop exists because that exact shape
+        # shipped: routes resolving records straight from params, gated by
+        # policies whose only check was `user_signed_in?`.
+        #
+        # The cop cannot see the controller from the policy file, so it flags
+        # every login-only gate and requires the developer to state the scoping
+        # mechanism in an adjacent comment (containing the configurable marker,
+        # default "login-only:"). Writing that sentence honestly is the check:
+        # it forces the question "what stops a stranger with someone else's id?"
+        # at the moment the gate is written. A login-only catch-all
+        # (`authorize :glib_all`) gates every action of the resource and
+        # deserves the same scrutiny.
+        #
+        # ## What an offense means
+        # An offense does NOT assert the gate is wrong. Many login-only gates
+        # are correct — the record IS the current user, the controller scopes
+        # every lookup through `current_user` associations, the route is
+        # token-addressed, or the data is public. The cop asserts that scoping
+        # story is UNDOCUMENTED at the gate, the one place a security reviewer
+        # will look for it. A correct-but-unmarked gate is still a violation
+        # until the story is written down; the marker is the intended
+        # resolution, not a workaround. On adoption, expect a one-time
+        # justification sweep over existing gates — writing each sentence
+        # honestly IS the audit.
+        #
+        # ## Remedy
+        # Prefer binding the decision to the record or context over justifying:
+        #
+        #   ❌ — every signed-in user passes; nothing binds them to the record
+        #   authorize :index do
+        #     user_signed_in?
+        #   end
+        #
+        #   ✔️ — the gate binds the user to the record
+        #   authorize :index do
+        #     record.is_a?(Project) && record.member?(current_user)
+        #   end
+        #
+        #   ✔️ — genuinely login-only, with the scoping stated where it can be
+        #   #    reviewed and re-checked
+        #   # login-only: the controller resolves records exclusively through
+        #   # current_user.projects; no params-derived id is honored.
+        #   authorize :index do
+        #     user_signed_in?
+        #   end
+        #
+        #   ✔️ — a policy that is login-only THROUGHOUT (current-user pages,
+        #   #    own-resource CRUD) states it once, above the class
+        #   # login-only: every action operates on current_user itself; the
+        #   # controller never resolves a record from params.
+        #   class MfaDevicePolicy < ApplicationPolicy
+        #     authorize :index do user_signed_in? end
+        #     authorize :create do user_signed_in? end
+        #   end
+        #
+        # A class-level marker covers every gate in the class — including ones
+        # added after the marker was written. Prefer per-gate markers unless
+        # the whole class genuinely shares one scoping story.
+        #
+        # ## Configuration
+        # `JustificationMarker` (default: `login-only:`) — the phrase the
+        # adjacent comment must contain (same line or the contiguous comment
+        # block directly above the gate, or above an enclosing class/module
+        # declaration to cover all gates within it).
+        #
+        # `LoginOnlyPredicates` (default: `user_signed_in?`, `everyone`) —
+        # bare predicates that make a gate login-only (or weaker) when they are
+        # its entire body. A literal `true` body is always flagged.
+        #
+        # NOTE: The cop is deliberately narrow: it flags only `authorize` blocks
+        # whose body is exactly one of the configured predicates (or `true`).
+        # Compound gates (`user_signed_in? && owner?`) and plain `def index?`
+        # policy methods are not tracked — the former carry more than login,
+        # the latter are building blocks whose decision point is elsewhere.
+        #
+        # @example
+        #   # bad — login-only gate with no stated scoping
+        #   authorize :index do
+        #     user_signed_in?
+        #   end
+        #
+        #   # bad — `true` is weaker still
+        #   authorize :show do
+        #     true
+        #   end
+        #
+        #   # good — decision bound to the record
+        #   authorize :show do
+        #     record.participant?(current_user)
+        #   end
+        #
+        #   # good — justified login-only gate
+        #   # login-only: records resolve through current_user associations only.
+        #   authorize :index do
+        #     user_signed_in?
+        #   end
+        class LoginOnlyPolicyJustification < Base
+          include AdjacentJustification
+
+          MSG = 'This gate authorizes EVERY signed-in user, including other tenants\' — if the ' \
+                'controller resolves any record from params, that is a cross-tenant IDOR. Bind the ' \
+                'decision to the record/context, or state the scoping mechanism in a "%<marker>s" ' \
+                'comment directly above (controller self-scope via current_user, non-enumerable ' \
+                'capability id, or genuinely public data).'.freeze
+
+          def on_block(node)
+            send_node = node.send_node
+            return unless send_node.method?(:authorize) && send_node.receiver.nil?
+            return unless login_only_body?(node.body)
+            return if adjacent_justification?(node) || class_level_justification?(node)
+
+            add_offense(node.body, message: format(MSG, marker: justification_marker))
+          end
+
+          private
+
+          # A marker above an enclosing class/module declaration covers every
+          # gate within it — for policies that are login-only throughout.
+          # standalone_only: without it, a marker trailing the PREVIOUS class's
+          # `end` would silence this class too.
+          def class_level_justification?(node)
+            node.each_ancestor(:class, :module).any? do |ancestor|
+              adjacent_justification?(ancestor, standalone_only: true)
+            end
+          end
+
+          def login_only_body?(body)
+            return false unless body
+            return true if body.true_type?
+
+            body.send_type? && body.receiver.nil? && body.arguments.empty? &&
+              login_only_predicates.include?(body.method_name)
+          end
+
+          def login_only_predicates
+            @login_only_predicates ||=
+              Array(cop_config.fetch('LoginOnlyPredicates', %w[user_signed_in? everyone])).map(&:to_sym)
+          end
+
+          def justification_marker
+            cop_config.fetch('JustificationMarker', 'login-only:')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/dev_doc/auth/no_record_presence_in_policy.rb

@@ -0,0 +1,104 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Auth
+        # Policy code must not use `record.present?` / `record.blank?` as an
+        # authorization signal.
+        #
+        # ## Rationale
+        # A policy's `record` answers "what is being acted on". Whether it is
+        # *present* is a **loading** outcome — it only proves the controller's
+        # lookup resolved something — never an **authorization** fact. Gating on
+        # presence fails in two distinct ways:
+        #
+        # 1. **Fail-open via placeholder records.** Pundit-style stacks support
+        #    headless policies, where the "record" is a Symbol naming the policy
+        #    rather than a model instance — and resource-resolution layers can
+        #    fall back to that Symbol when a lookup resolves nothing. A gate
+        #    written as `record.present?` is then true for exactly the request
+        #    it was written to refuse: the one whose record could not be
+        #    resolved. This is an observed production incident shape — a
+        #    cross-tenant guard reduced to `record.present?` passed for a
+        #    foreign-tenant id because the missing record arrived as a truthy
+        #    placeholder.
+        #
+        # 2. **Presence asserts nothing about the record.** Even when the record
+        #    is genuinely a model instance, `present?` says nothing about its
+        #    type, its tenant, or its relationship to the user. Authorization
+        #    must bind the user to the record — a type check plus the
+        #    ownership/attribute conditions that actually make the decision.
+        #
+        # ## Remedy
+        # Replace the presence check with a type check — it subsumes the nil
+        # guard and additionally asserts the record is the thing the policy
+        # believes it is — and bind the decision to the record's attributes:
+        #
+        #   ❌
+        #   authorize :create do
+        #     admin_of_organization?(organization) && record.present?
+        #   end
+        #
+        #   ✔️
+        #   authorize :create do
+        #     admin_of_organization?(organization) && record.is_a?(Member)
+        #   end
+        #
+        #   ✔️ — bind to the user, not to mere existence
+        #   def viewing_own_record?
+        #     record.is_a?(Member) && record.user_id == user.id
+        #   end
+        #
+        # NOTE: The cop is deliberately narrow: it flags `present?`/`blank?`
+        # only on the literal `record` receiver. Aliases (`def member = record`
+        # then `member.present?`) are not tracked — reviewers must catch those.
+        # Nil guards that precede attribute checks (`return false if
+        # record.nil?`) are not flagged; they fail closed and the attribute
+        # check that follows carries the authorization.
+        #
+        # @example
+        #   # bad — presence as the authorization answer
+        #   authorize :create do
+        #     record.present?
+        #   end
+        #
+        #   # bad — negated form, same loading fact
+        #   def member_missing?
+        #     record.blank?
+        #   end
+        #
+        #   # good — type check binds the gate to a real record
+        #   authorize :create do
+        #     record.is_a?(Member)
+        #   end
+        #
+        #   # good — authorization binds the user to the record
+        #   def viewing_own_record?
+        #     record.is_a?(Member) && record.user_id == user.id
+        #   end
+        class NoRecordPresenceInPolicy < Base
+          MSG = '`record.%<method>s` is a loading fact, not an authorization fact — resolution ' \
+                'fallbacks can make it true via a placeholder even when nothing was resolved. ' \
+                'Use a type check (`record.is_a?(SomeModel)`) plus the ownership/attribute ' \
+                'conditions that actually authorize this user.'.freeze
+
+          RESTRICT_ON_SEND = %i[present? blank?].freeze
+
+          def on_send(node)
+            return unless bare_record?(node.receiver)
+
+            add_offense(node.loc.selector, message: format(MSG, method: node.method_name))
+          end
+          alias on_csend on_send
+
+          private
+
+          # True if `node` is a bare `record` send (the Pundit-style policy
+          # reader — no receiver, no arguments).
+          def bare_record?(node)
+            node&.send_type? && node.method_name == :record && node.receiver.nil? && node.arguments.empty?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/dev_doc/auth/unscoped_find_justification.rb

@@ -0,0 +1,194 @@
+require_relative 'adjacent_justification'
+
+module RuboCop
+  module Cop
+    module DevDoc
+      module Auth
+        # A controller lookup that resolves a record from a client-controlled
+        # param on a bare model class (`Post.find(params[:id])`) must carry an
+        # adjacent justification naming where the record gets bound to the
+        # requester.
+        #
+        # ## Rationale
+        # `Post.find(params[:id])` reaches EVERY row of the table — the id is
+        # client-controlled and usually enumerable, so unless something else
+        # binds the resolved record to the requester (a policy that checks the
+        # record's owner/tenant, a tenant-scoped base controller, a
+        # non-enumerable capability id), any signed-in user can read or act on
+        # any tenant's record by walking ids. This cop exists because that
+        # exact shape shipped as cross-tenant IDORs: bare `find`s whose
+        # policies checked only "signed in" or bound the wrong level (the
+        # parent, not the specific record).
+        #
+        # The signal is inclusion-based: a CONSTANT receiver means unscoped. A
+        # lookup that travels through an association or `current_user`
+        # (`current_user.posts.find(...)`, `@project.members.find_by(...)`) has
+        # a non-constant receiver and passes silently — scoping through the
+        # association IS the fix this cop pushes toward.
+        #
+        # ## What an offense means
+        # An offense does NOT assert the site is vulnerable. The cop cannot see
+        # the policy, callback, or later guard that may already bind the
+        # record to the requester — it asserts the binding is UNDOCUMENTED at
+        # the lookup. A find that is safe through such controlling code is
+        # still a violation until the binding is either moved into the lookup
+        # (scoping) or stated in the marker comment; the marker is the intended
+        # resolution for legitimate root finds, not a workaround. On adoption,
+        # expect a one-time justification sweep over existing lookups — writing
+        # each binding sentence honestly IS the audit.
+        #
+        # ## Remedy
+        # Prefer scoping the lookup over justifying it:
+        #
+        #   ❌ — any signed-in user can reach any row
+        #   @post = Post.find(params[:id])
+        #
+        #   ✔️ — the lookup itself binds the record to the requester
+        #   @post = current_user.posts.find(params[:id])
+        #
+        #   ✔️ — nested records resolve through the already-bound parent
+        #   @comment = @post.comments.find_by(id: params[:comment_id])
+        #
+        #   ✔️ — genuinely necessary root find, binding stated for review
+        #   # unscoped-find: root record of the route; the policy receives it as
+        #   # resource: and checks record-derived tenant admin.
+        #   @post = Post.find(params[:id])
+        #
+        #   ✔️ — the lookup key itself is the binding: a non-enumerable
+        #   #    capability id (see NonEnumerableKeys)
+        #   @organization = Organization.find_by!(uuid: params[:organization_id])
+        #
+        # ## Configuration
+        # `JustificationMarker` (default: `unscoped-find:`) — the phrase the
+        # adjacent comment must contain (same line or the contiguous comment
+        # block directly above).
+        #
+        # `FinderMethods` (default: `find`, `find_by`, `find_by!`) — lookup
+        # methods the cop watches.
+        #
+        # `NonEnumerableKeys` (default: `uuid`, `token`, `secret_key`) — lookup
+        # keys treated as non-enumerable capability ids. A lookup is skipped
+        # only when its whole argument list is plain keyword pairs and every
+        # params-derived value is keyed by one of these
+        # (`find_by!(uuid: params[:id])`) — the unguessable key IS the binding,
+        # which the rationale above already endorses. The cop only trusts the
+        # key NAME; it cannot verify the column is actually unguessable, so
+        # only list keys your codebase reserves for high-entropy values.
+        # `slug` is deliberately not a default: slugs are public, guessable
+        # identifiers, not capabilities. Anything whose key can't be read off
+        # the call keeps the offense: positional lookups (`find(params[:id])` —
+        # even when `:id` holds a token), `**` splats, dynamic keys, and
+        # nested-hash values (association paths). Set to `[]` to disable the
+        # skip entirely.
+        #
+        # NOTE: The cop is deliberately narrow: it flags only a DIRECT constant
+        # receiver with an argument that references `params`. A chain rooted in
+        # a constant (`Post.includes(:x).find(params[:id])`) and an id copied
+        # into a local first (`id = params[:id]; Post.find(id)`) are not
+        # tracked — reviewers must catch those.
+        #
+        # @example
+        #   # bad — unscoped, client-controlled id
+        #   @post = Post.find(params[:id])
+        #
+        #   # bad — find_by hides the same reach
+        #   @post = Post.find_by(id: params[:post_id])
+        #
+        #   # good — scoped through the requester
+        #   @post = current_user.posts.find(params[:id])
+        #
+        #   # good — justified root find
+        #   # unscoped-find: policy binds via resource:; see PostPolicy#show?
+        #   @post = Post.find(params[:id])
+        class UnscopedFindJustification < Base
+          include AdjacentJustification
+
+          MSG = '`%<receiver>s.%<method>s(params[...])` resolves a record from a client-controlled ' \
+                'id with no scoping — unless something binds it to the requester, any signed-in ' \
+                'user reaches any tenant\'s record by enumerating ids. Scope the lookup through an ' \
+                'association/current_user, or state the binding in a "%<marker>s" comment ' \
+                'directly above.'.freeze
+
+          # FinderMethods is configuration-driven, so the name filter lives in
+          # on_send rather than RESTRICT_ON_SEND.
+          def on_send(node)
+            return unless finder_methods.include?(node.method_name)
+            return unless node.receiver&.const_type?
+            return unless node.arguments.any? { |argument| references_params?(argument) }
+            return if exempted?(node)
+
+            add_offense(node.loc.selector, message: offense_message(node))
+          end
+          alias on_csend on_send
+
+          private
+
+          def exempted?(node)
+            non_enumerable_keys_only?(node) || adjacent_justification?(node)
+          end
+
+          # True when the WHOLE argument list is readable keyword pairs and
+          # every params-derived value is keyed by a configured non-enumerable
+          # key (`find_by!(uuid: params[:id])`). Anything whose key can't be
+          # read — a positional argument, a `**` splat, a dynamic key — keeps
+          # the offense even when it doesn't itself touch params: the skip must
+          # see the entire lookup to vouch for it.
+          def non_enumerable_keys_only?(node)
+            return false if non_enumerable_keys.empty?
+
+            node.arguments.all? do |argument|
+              argument.hash_type? && argument.children.all? { |child| non_enumerable_pair?(child) }
+            end
+          end
+
+          def non_enumerable_pair?(child)
+            return false unless child.pair_type? # kwsplat — the key is invisible
+            return false if references_params?(child.key) # dynamic key
+
+            # A hash value (`uuid: { id: params[:id] }`) is an association
+            # path, not a keyed lookup — `uuid` would be the table, `id` the
+            # enumerable column.
+            !references_params?(child.value) ||
+              (non_enumerable_key?(child.key) && !child.value.hash_type?)
+          end
+
+          def non_enumerable_key?(key)
+            key.sym_type? && non_enumerable_keys.include?(key.value)
+          end
+
+          def non_enumerable_keys
+            @non_enumerable_keys ||=
+              Array(cop_config.fetch('NonEnumerableKeys', %w[uuid token secret_key])).map(&:to_sym)
+          end
+
+          def offense_message(node)
+            format(
+              MSG,
+              receiver: node.receiver.const_name,
+              method: node.method_name,
+              marker: justification_marker
+            )
+          end
+
+          def references_params?(node)
+            return true if bare_params?(node)
+
+            node.each_descendant(:send).any? { |descendant| bare_params?(descendant) }
+          end
+
+          def bare_params?(node)
+            node.send_type? && node.method_name == :params && node.receiver.nil?
+          end
+
+          def finder_methods
+            @finder_methods ||= Array(cop_config.fetch('FinderMethods', %w[find find_by find_by!])).map(&:to_sym)
+          end
+
+          def justification_marker
+            cop_config.fetch('JustificationMarker', 'unscoped-find:')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/dev_doc/rails/no_perform_later_in_model.rb

@@ -2,18 +2,32 @@ module RuboCop
   module Cop
     module DevDoc
       module Rails
-        # Avoid `perform_later` calls inside model files.
+        # Avoid `perform_later`/`deliver_later` calls inside model files.
         #
         # ## Rationale
-        # Avoid using ActiveJob inside Models, because:
+        # Enqueuing a job or mailer is execution-flow control — deciding *when*
+        # a side effect fires — and its home is the calling controller or job
+        # entry point (see the orchestration best-practice doc), because:
         #
         # - It is prone to conflicts between `transaction` and `perform_later`
         #   (the job may run before the transaction commits and read stale data
         #   — see `DevDoc/Rails/NoDeliverLaterInTransaction`).
-        # - Execution flow control should be done in the Controller, not in the
-        #   Model.
-        # - If it really must be done in the Model, name the method explicitly
-        #   so the side effect is obvious at the call site.
+        # - Flow control belongs to the Controller, not the Model. This governs
+        #   the *trigger* only: the mail itself stays composed in the Mailer
+        #   (parameters, templates — see the controller best-practice doc); the
+        #   controller merely calls `deliver_later`. Reuse across controllers
+        #   goes in a controller concern — DRY alone never justifies pushing a
+        #   trigger into a model.
+        # - The exception: an enqueue inseparable from a record state change
+        #   (e.g. a throttle stamp and its send that must never be split across
+        #   a boundary) stays in the model behind an explicitly named
+        #   `notify_*`/`send_*` method, so the side effect is obvious at the
+        #   call site.
+        #
+        # The boundary test: is the enqueue bound to a state change on this
+        # record, or is ordering already enforced by data flow (the caller can
+        # only enqueue with values that exist after the domain call returns)?
+        # The latter is flow control — trigger it from the controller.
         #
         #   ❌  (in app/models/order.rb)
         #   def finalize
@@ -21,18 +35,20 @@ module RuboCop
         #     OrderJob.perform_later(self)
         #   end
         #
-        #   ✔️ Explicit method name signals the side effect; reviewers
-        #     immediately see that this should not be called inside a
+        #   ✔️ State-coupled enqueue behind an explicit `notify_*` name; the
+        #     side effect is obvious at the call site, and reviewers
+        #     immediately see that this must not be called inside a
         #     `transaction` block.
-        #   def save_with_email_sending
-        #     save!
+        #   def notify_finalized
+        #     update!(finalize_notified_at: Time.current)
         #     OrderJob.perform_later(self)
         #   end
         #
         # NOTE: This cop flags *any* `perform_later` in `app/models/**/*.rb`,
         # including the legitimate "explicitly named method" case above. The
         # cop is intentionally conservative — disable per-line with a rubocop
-        # comment when you have deliberately followed the naming convention.
+        # comment stating the justification when you have deliberately followed
+        # the naming convention.
         #
         # @example
         #   # bad (in app/models/order.rb)
@@ -41,9 +57,9 @@ module RuboCop
         #     OrderJob.perform_later(self)
         #   end
         #
-        #   # good — explicit method communicates the side effect
-        #   def finalize_with_job
-        #     save!
+        #   # good — state-coupled enqueue behind an explicitly named method
+        #   def notify_finalized
+        #     update!(finalize_notified_at: Time.current)
         #     OrderJob.perform_later(self)
         #   end
         class NoPerformLaterInModel < Base