rubocop-dev_doc 0.12.1 → 0.12.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a70fbdce97064f296200b1a77f663eb5c7f928973ea7be693d0ad36f1ff015bb
-  data.tar.gz: 3e285799f1deffcb5bd30c90d61b2f3bd5438cb7a6a30b358dd60eba61a31072
+  metadata.gz: 4840aa1ca5c8a4ee2f5dfcb5b2e6880dbe7966d451b8502e0983e8eb63e9b04c
+  data.tar.gz: 4cc9d0f5a9e352f4b361b831250e5683242a0b35578b8abb43eb3535a18c9a1c
 SHA512:
-  metadata.gz: 7eb23bbe57954d976ce2975b1eb35a616a306b56bfacacbbc18c03c40bfce86564efe48990649b4137ebdbe7f3773f77f4c3649df27a3bc3d33cc763afc10717
-  data.tar.gz: 2593c0b78fcc7d82755f1ae7ae7ee81e70a362f3f1e1eff2636ebd2b221c496304c3816cca489fa50d8f67711159ade8ecc7bd88dd2d705f3c820105579ae49c
+  metadata.gz: 8c66389a73be82ba697f12708c89023851dc246caa0b3439a389948c8490b0b903a8dd14b90e7f54fa33698bc5e441fe50db7465d5d808e46db72086da0a5305
+  data.tar.gz: 69fd78aefb3b759863f7a45e3de18bb84bdccf52e1485a4dac0ea9151e0790fcbfa13c1a45d6dffd79bd6fbfff478020231b8b5aafc1d3e9f7a21b2668437fbf

data/config/default.yml

@@ -722,6 +722,66 @@ DevDoc/Auth/RolePredicateOutsidePolicy:
     - "test/**/*"
     - "spec/**/*"
 
+# Presence of the policy record is a LOADING fact, not an authorization fact.
+# Headless-policy stacks can hand `record` a truthy placeholder (the policy-name
+# Symbol) when a lookup resolves nothing, turning `record.present?` fail-open for
+# exactly the request it was written to refuse. Observed in production code as a
+# cross-tenant guard reduced to `record.present?`. The remedy — a type check plus
+# ownership/attribute conditions — is strictly stronger in every case, so there
+# is no legitimate hit to tolerate.
+DevDoc/Auth/NoRecordPresenceInPolicy:
+  Description: "`record.present?`/`record.blank?` is a loading fact, not an authorization fact; use a type check (`record.is_a?(SomeModel)`) plus ownership/attribute conditions."
+  Enabled: true
+  Include:
+    - "app/policies/**/*.rb"
+
+# A login-only gate authorizes every signed-in user, including other tenants'.
+# That is safe only when something else scopes what the action reaches — and the
+# cop cannot see the controller from the policy file, so it makes the developer
+# state that scoping in an adjacent "login-only:" comment. Expect a one-time
+# justification sweep on adoption; writing each sentence honestly IS the audit
+# ("what stops a stranger with someone else's id?"). Observed shipped IDORs had
+# exactly this shape: params-resolved records behind user_signed_in?-only gates.
+# A policy that is login-only throughout (current-user pages, own-resource CRUD)
+# can carry one marker above its class instead of one per gate.
+DevDoc/Auth/LoginOnlyPolicyJustification:
+  Description: "A gate that is only `user_signed_in?`/`everyone`/`true` needs an adjacent `login-only:` comment stating where per-record scoping happens — or bind the decision to the record."
+  Enabled: true
+  JustificationMarker: "login-only:"
+  LoginOnlyPredicates:
+    - user_signed_in?
+    - everyone
+  Include:
+    - "app/policies/**/*.rb"
+
+# `Post.find(params[:id])` reaches every row from a client-controlled, usually
+# enumerable id. Unless the policy binds the resolved record (or its tenant) to
+# the requester, that is a cross-tenant IDOR — the observed shipped shape. The
+# fix the cop pushes toward is scoping the lookup itself (current_user.posts,
+# parent association); a genuinely necessary root find carries an adjacent
+# "unscoped-find:" comment naming the binding. Pairs with
+# LoginOnlyPolicyJustification: shipping a new IDOR past both requires writing
+# two dishonest justifications in two files.
+DevDoc/Auth/UnscopedFindJustification:
+  Description: "A `Model.find(params[...])` with a constant receiver is unscoped; scope it through an association/current_user or add an adjacent `unscoped-find:` comment naming the binding."
+  Enabled: true
+  JustificationMarker: "unscoped-find:"
+  FinderMethods:
+    - find
+    - find_by
+    - find_by!
+  # Lookup keys treated as non-enumerable capability ids: a keyword lookup
+  # whose params-derived values are all keyed by one of these
+  # (`find_by!(uuid: params[:id])`) is skipped — the unguessable key is the
+  # binding. Key NAMES only; the cop cannot verify entropy. `slug` is
+  # deliberately absent (public, guessable). Set to [] to disable.
+  NonEnumerableKeys:
+    - uuid
+    - token
+    - secret_key
+  Include:
+    - "app/controllers/**/*.rb"
+
 DevDoc/I18n/AvoidTitleizeHumanize:
   Description: "Avoid `.titleize`/`.humanize` for display text; it's English-only and bypasses I18n. Use `t(...)`."
   # A review aid, not a clean lint: it can't tell a display string from one

data/lib/dev_doc/test/lints/cross_tenant_canary_check.rb

@@ -0,0 +1,111 @@
+module DevDoc
+  module Test
+    module Lints
+      # Cross-tenant canary sweep: catches a tenant-isolation leak by
+      # *observing responses/side-effects*, not by inspecting source. The
+      # static auth cops (DevDoc/Auth/*) flag the leak-shaped code patterns
+      # we have seen before; this lint fails when another tenant's data
+      # actually APPEARS somewhere a persona must not see it — regardless of
+      # which novel controller shape caused it.
+      #
+      # ## The canary convention (consumer-side)
+      # Fixtures give every tenant globally-unique, greppable markers on
+      # fields that render into responses (e.g. `CANARY-<tenant>-<field>`),
+      # seeded for at least two tenants so "foreign" is well-defined. Markers
+      # must be STATIC fixture strings — never minted at runtime — so a leak
+      # is a pure substring test with zero false positives.
+      #
+      # ## What it covers, honestly
+      # - A passive scan of every crawled response catches leaks on routes a
+      #   persona can reach. It reads CONTENT, not status: an endpoint that
+      #   returns 200 by design but embeds foreign data (a metadata preview)
+      #   is caught where a status-only probe passes it.
+      # - An adversarial replay (id-like params substituted with a foreign
+      #   tenant's ids) reaches leaks no page ever links the persona to.
+      #   Only 2xx bodies are asserted on — a substituted id that 404s has
+      #   no body to leak, and status is not the signal.
+      # - An outbound-recipient scan catches side-effect leaks (mail sent to
+      #   a foreign tenant's address) that leave no trace in any response.
+      #
+      # NOT covered: anything a persona can neither be linked to nor have
+      # its params mutated into, and any field carrying no marker. The lint
+      # reduces the cross-tenant surface; it does not eliminate it.
+      #
+      # ## Usage
+      # This file holds only the pure, Rails-free core (so the gem's own
+      # spec suite can load it). Projects include the runtime wrapper into
+      # their base integration test instead — see
+      # DevDoc::Test::Lints::CrossTenantCanarySweep.
+      module CrossTenantCanaryCheck
+        # The marker convention: `CANARY-<tenant>-<field>`. Consumers seed these
+        # STATIC strings onto tenant-owned fields. The tenant id is embedded, so
+        # collection needs no per-model knowledge — grouping is by the marker
+        # itself.
+        MARKER = /CANARY-\d+-[a-z0-9-]+/
+        TENANT_FROM_MARKER = /\ACANARY-(\d+)-/
+
+        module_function
+
+        # Build `{ tenant_key => [markers...] }` from arbitrary text sources —
+        # fixture-file contents, DB column values, rendered snapshots — grouping
+        # each marker by the tenant id embedded in it. Pure string logic: the
+        # consumer owns WHERE the text comes from (fixtures path, models), the
+        # gem owns the marker format and the grouping. Deduped per tenant.
+        def tenant_registry(texts)
+          registry = Hash.new { |hash, key| hash[key] = [] }
+          texts.each do |text|
+            text.to_s.scan(MARKER).each do |marker|
+              registry[marker[TENANT_FROM_MARKER, 1]] << marker
+            end
+          end
+          registry.transform_values(&:uniq)
+        end
+
+        # Markers belonging to every tenant OUTSIDE the persona's allowed
+        # set. Takes a SET of allowed tenant keys, not a single tenant — a
+        # global admin legitimately sees every tenant (pass all keys and the
+        # check is vacuous for it), and hierarchical tenants can grant a
+        # parent visibility into its children. Keys compare as strings so
+        # fixture-derived integers and configured symbols can't miss.
+        def foreign_markers(allowed_tenant_keys, registry)
+          allowed = allowed_tenant_keys.map(&:to_s)
+          registry.reject { |key, _| allowed.include?(key.to_s) }
+                  .values.flatten.uniq
+        end
+
+        # The subset of markers present in the body. Boundary-aware, like
+        # CopDriftCheck.unmentioned_cops: a marker that PREFIXES a longer
+        # marker must not match on the longer one's occurrence, or the
+        # failure names the wrong leaked field.
+        def leaked_markers(body, markers)
+          return [] if body.nil? || body.empty?
+
+          markers.select { |marker| body.match?(/#{Regexp.escape(marker)}(?![A-Za-z0-9-])/) }
+        end
+
+        # Outbound recipients that belong to a foreign tenant. Emails are
+        # case-insensitive per RFC domain rules and common practice, so the
+        # intersection normalizes case on both sides.
+        def leaked_recipients(recipients, foreign_emails)
+          normalize(recipients) & normalize(foreign_emails)
+        end
+
+        # Param keys worth substituting with a foreign tenant's values in an
+        # adversarial replay: `id`, anything ending `_id`, plus an explicit
+        # project-configured allowlist (e.g. a display-mode toggle that
+        # switches a form into a data-bearing preview).
+        def id_like_param_keys(keys, extra: [])
+          extras = extra.map(&:to_s)
+          keys.map(&:to_s)
+              .select { |key| key == 'id' || key.end_with?('_id') || extras.include?(key) }
+              .uniq
+        end
+
+        def normalize(emails)
+          Array(emails).compact.map { |email| email.to_s.downcase }
+        end
+        private_class_method :normalize
+      end
+    end
+  end
+end

data/lib/dev_doc/test/lints/cross_tenant_canary_sweep.rb

@@ -0,0 +1,103 @@
+require 'dev_doc/test/lints/cross_tenant_canary_check'
+
+module DevDoc
+  module Test
+    module Lints
+      # L1 of the cross-tenant canary sweep (see CrossTenantCanaryCheck for the
+      # doctrine and the honest coverage/miss statement). Passive: it asserts
+      # that no response a persona receives contains another tenant's canary
+      # marker. It adds no requests of its own — it rides whatever crawl/replay
+      # the host test already drives.
+      #
+      # Include into the project's base integration test:
+      #
+      #   Glib::IntegrationTest.include DevDoc::Test::Lints::CrossTenantCanarySweep
+      #
+      # ## The choke point
+      # Every request helper (`get`/`post`/...) funnels through the verb methods
+      # this module overrides (the module sits ahead of the framework Runner in
+      # the MRO). A JSON crawler that drives requests via `send(:get, ...)` on
+      # the test instance is caught the same way as a direct call — no crawler
+      # changes needed. After `super` returns, `response.body` holds the body to
+      # scan.
+      #
+      # ## Where this has signal, and where it deliberately doesn't
+      # The scan only sees what the response actually rendered:
+      # - Full-render harnesses (a crawler that renders pages to follow their
+      #   links; a permission replay run in FULL mode) → real signal: a foreign
+      #   marker in a persona's own reachable page is a data-bleed leak.
+      # - A permission replay in its default SKIP mode short-circuits the
+      #   controller action to a status-only body, so there is no rendered
+      #   content to scan. That harness catches cross-tenant access at the
+      #   STATUS level (its response-matrix snapshot); this lint contributes no
+      #   content signal there, and that is fine — the two are complementary,
+      #   not redundant. Passing this lint in skip mode is not evidence of
+      #   isolation; the matrix is.
+      # This layer is passive, so it never reaches a leak a persona is not
+      # already linked to — that is the adversarial replay's job (L2/L3), which
+      # the host app owns because param-mutation and mail-capture are too
+      # app-shaped to generalize. Keep this core pure.
+      #
+      # ## Consumer contract
+      # The including test must provide two things, refreshed per persona:
+      # - `canary_registry` → `{ tenant_key => [markers...] }`, scanned from
+      #   fixtures once (static strings only — never runtime-minted, per the
+      #   determinism doctrine).
+      # - `canary_allowed_tenant_keys` → the tenant keys the CURRENT persona may
+      #   legitimately see. A single-tenant member returns its one key; a global
+      #   admin returns every key (making the scan vacuous for it — correct, it
+      #   sees everything); a parent in a tenant hierarchy returns itself plus
+      #   its descendants. Returning nil disables the scan for that request
+      #   (e.g. before any persona has logged in).
+      module CrossTenantCanarySweep
+        %i[get post patch put delete head options].each do |verb|
+          define_method(verb) do |*args, **kwargs, &block|
+            result = super(*args, **kwargs, &block)
+            __dev_doc_scan_for_foreign_canary
+            result
+          end
+        end
+
+        private
+
+        def __dev_doc_scan_for_foreign_canary
+          allowed = canary_allowed_tenant_keys
+          return if allowed.nil?
+
+          registry = canary_registry
+          return if registry.nil? || registry.empty?
+
+          foreign = CrossTenantCanaryCheck.foreign_markers(allowed, registry)
+          leaked = CrossTenantCanaryCheck.leaked_markers(__dev_doc_response_body, foreign)
+          return if leaked.empty?
+
+          raise Minitest::Assertion, __dev_doc_canary_message(allowed, leaked)
+        end
+
+        def __dev_doc_response_body
+          response&.body.to_s
+        rescue StandardError
+          ''
+        end
+
+        def __dev_doc_canary_message(allowed, leaked)
+          <<~MSG
+            Cross-tenant leak: this persona (allowed tenants: #{Array(allowed).join(', ')}) received a
+            response containing #{leaked.join(', ')}, which belongs to a tenant it must not see.
+            Route: #{__dev_doc_route_label}
+            Another tenant's data rendered into this persona's response — a cross-tenant read leak.
+            Bind the record to the requester: scope the lookup through the persona's tenant
+            (current_user / current organization), or gate the policy on the record's tenant.
+            See DevDoc/Auth/UnscopedFindJustification and DevDoc/Auth/LoginOnlyPolicyJustification
+            for the static companions.
+          MSG
+        end
+
+        def __dev_doc_route_label
+          req = request
+          req ? "#{req.request_method} #{req.fullpath}" : '(unknown)'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Auth
+        # The adjacent-justification contract shared by the auth "flag and make
+        # the developer state the mechanism" cops: an offense is silenced by a
+        # comment containing the cop's marker phrase either on the flagged
+        # node's own line (trailing) or in the contiguous comment block ending
+        # on the line directly above it. Adjacency is the point — a marker
+        # elsewhere in the file justifies nothing. Host cops must provide
+        # `justification_marker`.
+        #
+        # With `standalone_only: true` the upward walk only crosses comment-ONLY
+        # lines. Use this when the checked node is a class/module declaration:
+        # there the "trailing comment on a preceding code line" rule would let a
+        # marker trailing the PREVIOUS class's `end` silence the next class.
+        module AdjacentJustification
+          private
+
+          def adjacent_justification?(node, standalone_only: false)
+            marker = justification_marker.downcase
+            comments_by_line = processed_source.comments.group_by { |comment| comment.location.line }
+
+            return true if contains_marker?(comments_by_line[node.first_line], marker)
+
+            marker_in_block_above?(node.first_line - 1, comments_by_line, marker, standalone_only)
+          end
+
+          # Walk the contiguous comment block upward from the line directly
+          # above. A trailing comment on a preceding code line also counts —
+          # still adjacent, still a deliberate statement — except in
+          # standalone_only mode.
+          def marker_in_block_above?(line, comments_by_line, marker, standalone_only)
+            while (line_comments = comments_by_line[line])
+              break if standalone_only && !comment_only_line?(line)
+              return true if contains_marker?(line_comments, marker)
+
+              line -= 1
+            end
+
+            false
+          end
+
+          def comment_only_line?(line)
+            processed_source.lines[line - 1].lstrip.start_with?('#')
+          end
+
+          def contains_marker?(comments, marker)
+            Array(comments).any? { |comment| comment.text.downcase.include?(marker) }
+          end
+        end
+      end
+    end
+  end
+end

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/dev_doc/version.rb

@@ -1,5 +1,5 @@
 module RuboCop
   module DevDoc
-    VERSION = "0.12.1".freeze
+    VERSION = "0.12.2".freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-dev_doc
 version: !ruby/object:Gem::Version
-  version: 0.12.1
+  version: 0.12.2
 platform: ruby
 authors:
 - dev-doc contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-13 00:00:00.000000000 Z
+date: 2026-07-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -93,15 +93,21 @@ files:
 - lib/dev_doc/test/lints/cop_drift_check.rb
 - lib/dev_doc/test/lints/cop_drift_test.rb
 - lib/dev_doc/test/lints/cron_schedule.rb
+- lib/dev_doc/test/lints/cross_tenant_canary_check.rb
+- lib/dev_doc/test/lints/cross_tenant_canary_sweep.rb
 - lib/dev_doc/test/lints/duplicate_snapshot.rb
 - lib/dev_doc/test/lints/http_driven_controller_tests.rb
 - lib/dev_doc/test/lints/no_file_excludes.rb
 - lib/dev_doc/test/pseudo_i18n_crawler.rb
 - lib/rubocop-dev_doc.rb
+- lib/rubocop/cop/dev_doc/auth/adjacent_justification.rb
 - lib/rubocop/cop/dev_doc/auth/current_user_branching.rb
 - lib/rubocop/cop/dev_doc/auth/current_user_branching_helpers.rb
 - lib/rubocop/cop/dev_doc/auth/load_resource_current_user_guard.rb
+- lib/rubocop/cop/dev_doc/auth/login_only_policy_justification.rb
+- lib/rubocop/cop/dev_doc/auth/no_record_presence_in_policy.rb
 - lib/rubocop/cop/dev_doc/auth/role_predicate_outside_policy.rb
+- lib/rubocop/cop/dev_doc/auth/unscoped_find_justification.rb
 - lib/rubocop/cop/dev_doc/i18n/avoid_titleize_humanize.rb
 - lib/rubocop/cop/dev_doc/i18n/localizable_props.rb
 - lib/rubocop/cop/dev_doc/i18n/report_text.rb