mecha_authorize 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8f08a1ab8bc1c24142b6a7938ae981b7df4ac925d324c5b709e01032ac2afb03
+  data.tar.gz: 5ecf4101189a14053e7692ba44c3fee6c3951d53b246dc95976d237291efdc82
+SHA512:
+  metadata.gz: e5ee312dbd97f3511a143aa241e187b7897de4dce760ba17a1a7f0a3ed63de1b7912bcd75829fd2fa02aff0a338b932a0deb5d3416dc5d51127dbe767ed20720
+  data.tar.gz: dda55c536ca1c54706e6a052c62520b97328125b73f174917ca2afd9dd22c379f787750900ee0825cd9940c2dfe0f98687fd7e2c4c444c1c3745622b35fcef22

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright 2026 Jeff Lunt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,162 @@
+# MechaAuthorize
+
+`mecha_authorize` provides a YAML-driven, closed-by-default route authorization system for Rails applications. Every incoming request is evaluated against an explicit route registry before controller actions run, with built-in static route parity auditing and behavioral persona matrix probing.
+
+## Installation
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem "mecha_authorize"
+```
+
+Or if developing locally:
+
+```ruby
+gem "mecha_authorize", path: "~/code/mecha_authorize"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### 1. Define `config/mecha_authorize.yml`
+
+Declare your application routes and role permissions in `config/mecha_authorize.yml`. Any route not matching an entry in this file is denied by default (404).
+
+```yaml
+debug_colorization:
+  public: :green
+  admin: :light_red
+  user_ui: :light_purple
+  user_api: :light_cyan
+  none: :dark_grey
+
+routes:
+  - route_pattern: "/"
+    verb: "GET"
+    public: true
+    admin: false
+    user_ui: false
+    user_api: false
+
+  - route_pattern: "/home"
+    verb: "GET"
+    public: false
+    admin: true
+    user_ui: true
+    user_api: false
+
+  - route_pattern: "/admin/*"
+    verb: "*"
+    public: false
+    admin: true
+    user_ui: false
+    user_api: false
+
+  - route_pattern: "/api/v1/items/:id"
+    verbs: ["GET", "PATCH", "DELETE"]
+    public: false
+    admin: false
+    user_ui: false
+    user_api: true
+```
+
+### 2. Configure the Initializer
+
+Create `config/initializers/mecha_authorize.rb` to define role resolvers and include the controller concern:
+
+```ruby
+# config/initializers/mecha_authorize.rb
+require "mecha_authorize"
+
+MechaAuthorize.configure do |config|
+  config.config_path = Rails.root.join("config/mecha_authorize.yml")
+
+  config.define_role :public do |_user, _request|
+    true
+  end
+
+  config.define_role :admin do |user, _request|
+    user&.admin? || false
+  end
+
+  config.define_role :user_ui do |user, _request|
+    user&.user_permission&.user_ui? || false
+  end
+
+  config.define_role :user_api do |user, _request|
+    user&.user_permission&.user_api? || false
+  end
+
+  config.on_unauthorized = ->(controller) {
+    controller.head :not_found
+  }
+end
+
+ActiveSupport.on_load(:action_controller_base) do
+  include MechaAuthorize::Controller
+end
+```
+
+### 3. Rake Tasks & Auditing
+
+`mecha_authorize` automatically registers Rake tasks via its Railtie:
+
+```bash
+# Print all routes and their colorized authorization matrix
+bin/rails mecha_authorize
+
+# Statically audit routes for dead rules and mounted engine bypasses
+bin/rails mecha_authorize:verify:static
+
+# Run behavioral persona matrix tests
+bin/rails mecha_authorize:verify:behavioral
+
+# Run both static and behavioral verification
+bin/rails mecha_authorize:verify
+```
+
+### 4. Dynamic Parallel Matrix Testing in Consuming Apps
+
+`mecha_authorize` ships with [`MechaAuthorize::MatrixTest`](lib/mecha_authorize/matrix_test.rb), which dynamically generates an individual Minitest test method per route so that Minitest's parallel worker pool executes route probes across all CPU cores.
+
+In your consuming Rails application's `test/test_helper.rb`, configure the persona callbacks and require the matrix test:
+
+```ruby
+MechaAuthorize.configuration.configure_test_matrix(
+  setup: -> {
+    # Set up test users / tokens for each role
+  },
+  teardown: -> {
+    # Optional teardown logic
+  },
+  personas: -> {
+    {
+      anonymous: ->(session) { session.reset!; {} },
+      admin: ->(session) { login_as(session, @admin_user); {} },
+      user_ui: ->(session) { login_as(session, @ui_user); {} },
+      user_api: ->(_session) { { "Authorization" => "Bearer #{@api_jwt}" } },
+      restricted: ->(session) { login_as(session, @restricted_user); {} }
+    }
+  }
+)
+
+require "mecha_authorize/matrix_test" unless ENV["MECHA_MATRIX_STANDALONE"] == "1"
+```
+
+## Running Tests
+
+To run the gem's standalone test suite:
+
+```bash
+bundle exec rake test
+```
+
+## License
+
+Copyright 2026 Jeff Lunt. Released under the [MIT License](LICENSE).

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/lib/mecha_authorize/auditor/prober.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module MechaAuthorize
+  module Auditor
+    class Prober
+      ProbeFailure = Struct.new(:route, :persona, :expected_status, :actual_status, :message, keyword_init: true)
+
+      Result = Struct.new(:probed_count, :failures, keyword_init: true) do
+        def success?
+          failures.empty?
+        end
+      end
+
+      DEFAULT_PARAM_SUBSTITUTIONS = {
+        ":id" => "1",
+        ":card_id" => "card-1",
+        ":table_id" => "table-1",
+        ":provider" => "google_oauth2",
+        ":application_id" => "app-1",
+        ":queue_id" => "queue-1",
+        ":filename" => "test.png",
+        ":path" => "test"
+      }.freeze
+
+      def initialize(integration_session = nil, matcher = MechaAuthorize.matcher)
+        @session = integration_session
+        @matcher = matcher
+      end
+
+      def probe_all_routes(persona_generator)
+        failures = []
+        probed_count = 0
+
+        routes = collect_prober_routes
+
+        routes.each do |route_info|
+          route_res = probe_route(route_info, persona_generator)
+          probed_count += route_res.probed_count
+          failures.concat(route_res.failures)
+        end
+
+        Result.new(probed_count: probed_count, failures: failures)
+      end
+
+      def probe_route(route_info, persona_generator)
+        failures = []
+        probed_count = 0
+
+        verb = route_info[:verb]
+        raw_path = route_info[:path]
+        path = substitute_params(raw_path)
+        rule = @matcher.match(verb, path, raw_path)
+
+        personas = persona_generator.respond_to?(:call) ? persona_generator.call : persona_generator
+
+        personas.each do |persona_name, user_setup|
+          probed_count += 1
+          expected_status = calculate_expected_status(raw_path, rule, persona_name)
+
+          extra_headers = user_setup.call(@session) || {}
+
+          actual_status = dispatch_probe_request(verb, path, extra_headers)
+
+          unless status_matches?(actual_status, expected_status)
+            failures << ProbeFailure.new(
+              route: "#{verb} #{raw_path} (#{path})",
+              persona: persona_name,
+              expected_status: expected_status,
+              actual_status: actual_status,
+              message: "Expected HTTP #{expected_status} but received HTTP #{actual_status}"
+            )
+          end
+        end
+
+        Result.new(probed_count: probed_count, failures: failures)
+      end
+
+      def substitute_params(path)
+        result = path.dup
+        DEFAULT_PARAM_SUBSTITUTIONS.each do |param, val|
+          result.gsub!(param, val)
+        end
+        # Generic fallback for any remaining :param
+        result.gsub!(/:[a-zA-Z_]+/, "1")
+        result
+      end
+
+      def collect_prober_routes
+        self.class.collect_prober_routes
+      end
+
+      def self.collect_prober_routes
+        return [] unless defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+
+        routes = Rails.application.routes.routes.map do |r|
+          ActionDispatch::Routing::RouteWrapper.new(r)
+        end.reject(&:internal?)
+
+        all = []
+
+        routes.each do |r|
+          if r.engine?
+            engine_routes = r.rack_app.routes
+            engine_routes = engine_routes.routes if engine_routes.is_a?(ActionDispatch::Routing::RouteSet)
+            clean_mount = r.path.sub("(.:format)", "").sub("/*path", "").sub("/*filename", "").chomp("/")
+
+            engine_routes.map { |er| ActionDispatch::Routing::RouteWrapper.new(er) }.reject(&:internal?).each do |er|
+              verb = er.verb.to_s.empty? ? "*" : er.verb.to_s.upcase
+              full_path = "#{clean_mount}#{er.path}".sub("(.:format)", "")
+              all << { verb: verb, path: full_path }
+            end
+          else
+            verb = r.verb.to_s.empty? ? "*" : r.verb.to_s.upcase
+            all << { verb: verb, path: r.path.sub("(.:format)", "") }
+          end
+        end
+
+        all.uniq { |r| [r[:verb], r[:path]] }
+      end
+
+      private
+
+      def calculate_expected_status(raw_path, rule, persona_name)
+        sentinel = MechaAuthorize.configuration.probe_status
+        is_api = raw_path.start_with?("/api/")
+
+        return 404 if rule.nil?
+
+        if rule[:public]
+          return sentinel
+        end
+
+        case persona_name
+        when :anonymous
+          is_api ? [400, 401, 404] : 404
+        when :admin
+          rule[:admin] ? sentinel : (is_api ? [400, 401, 403, 404] : 404)
+        when :user_ui
+          (rule[:user_ui] && !is_api) ? sentinel : (is_api ? [400, 401, 403, 404] : 404)
+        when :user_api
+          rule[:user_api] ? sentinel : (is_api ? [400, 401, 403, 404] : 404)
+        when :restricted
+          is_api ? [400, 401, 403, 404] : 404
+        else
+          404
+        end
+      end
+
+      def status_matches?(actual_status, expected_status)
+        if expected_status.is_a?(Array)
+          expected_status.include?(actual_status)
+        else
+          actual_status == expected_status
+        end
+      end
+
+      def dispatch_probe_request(verb, path, extra_headers = {})
+        headers = { MechaAuthorize.configuration.probe_header => "1" }.merge(extra_headers)
+
+        case verb.to_s.upcase
+        when "GET", "*"
+          @session.get path, headers: headers
+        when "POST"
+          @session.post path, headers: headers
+        when "PATCH"
+          @session.patch path, headers: headers
+        when "PUT"
+          @session.put path, headers: headers
+        when "DELETE"
+          @session.delete path, headers: headers
+        when "HEAD"
+          @session.head path, headers: headers
+        else
+          @session.get path, headers: headers
+        end
+
+        @session.response.status
+      rescue ActionController::RoutingError
+        404
+      end
+    end
+  end
+end

data/lib/mecha_authorize/auditor/static.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module MechaAuthorize
+  module Auditor
+    class Static
+      Result = Struct.new(
+        :mapped_routes,
+        :unmapped_routes,
+        :dead_rules,
+        :engine_warnings,
+        keyword_init: true
+      ) do
+        def success?
+          dead_rules.empty? && engine_warnings.empty?
+        end
+      end
+
+      def initialize(matcher = MechaAuthorize.matcher)
+        @matcher = matcher
+      end
+
+      def audit
+        rails_routes = collect_all_routes
+        mapped = []
+        unmapped = []
+        matched_rules = Set.new
+
+        rails_routes.each do |r|
+          rule = @matcher.match_route_spec(r[:verb], r[:path])
+
+          if rule
+            mapped << r.merge(rule: rule)
+            matched_rules << rule
+          else
+            unmapped << r
+          end
+        end
+
+        # Check for dead/stale rules in mecha_authorize.yml
+        # A rule is dead if it does not match any actual Rails route and is not a wildcard
+        dead_rules = []
+        @matcher.all_rules.each do |(verb, pattern), rule|
+          next if pattern.include?("*") # Wildcards cover dynamic/future paths
+
+          # Check if any route matched this specific pattern and verb
+          matched = rails_routes.any? do |r|
+            (verb == "*" || r[:verb] == "*" || r[:verb] == verb) &&
+              route_matches_pattern?(r[:path], pattern)
+          end
+
+          dead_rules << { verb: verb, pattern: pattern, rule: rule } unless matched
+        end
+
+        # Check mounted engines for authorization gate coverage
+        engine_warnings = audit_mounted_engines
+
+        Result.new(
+          mapped_routes: mapped,
+          unmapped_routes: unmapped,
+          dead_rules: dead_rules,
+          engine_warnings: engine_warnings
+        )
+      end
+
+      private
+
+      def route_matches_pattern?(route_path, config_pattern)
+        clean_route = route_path.sub(/\(\.:format\)$/, "")
+        clean_config = config_pattern.sub(/\(\.:format\)$/, "")
+
+        return true if clean_route == clean_config
+
+        # Check parameterized segment matching
+        route_regex = pattern_to_regex(clean_route)
+        config_regex = pattern_to_regex(clean_config)
+
+        route_regex.match?(clean_config) || config_regex.match?(clean_route)
+      end
+
+      def pattern_to_regex(pattern)
+        segments = pattern.split("/", -1)
+        regex_segments = segments.map do |seg|
+          if seg.start_with?(":")
+            "[^/]+"
+          elsif seg.start_with?("*")
+            ".*"
+          else
+            Regexp.escape(seg)
+          end
+        end
+        Regexp.new("\\A#{regex_segments.join('/')}\\z")
+      end
+
+      def collect_all_routes
+        routes = Rails.application.routes.routes.map do |r|
+          ActionDispatch::Routing::RouteWrapper.new(r)
+        end.reject(&:internal?)
+
+        all = []
+
+        routes.each do |r|
+          if r.engine?
+            engine_routes = r.rack_app.routes
+            engine_routes = engine_routes.routes if engine_routes.is_a?(ActionDispatch::Routing::RouteSet)
+            clean_mount = r.path.sub("(.:format)", "").sub("/*path", "").sub("/*filename", "").chomp("/")
+
+            engine_routes.map { |er| ActionDispatch::Routing::RouteWrapper.new(er) }.reject(&:internal?).each do |er|
+              verb = extract_verb(er)
+              full_path = "#{clean_mount}#{er.path}".sub("(.:format)", "")
+              all << { verb: verb, path: full_path, engine: r.rack_app.name }
+            end
+          else
+            verb = extract_verb(r)
+            all << { verb: verb, path: r.path.sub("(.:format)", ""), engine: nil }
+          end
+        end
+
+        all
+      end
+
+      def extract_verb(route_wrapper)
+        raw_verb = route_wrapper.verb.to_s
+        raw_verb.empty? ? "*" : raw_verb.upcase
+      end
+
+      def audit_mounted_engines
+        warnings = []
+        routes = Rails.application.routes.routes.select { |r| r.app.engine? if r.app.respond_to?(:engine?) }
+
+        routes.each do |route|
+          rack_app = route.app.rack_app
+          engine_name = rack_app.name || rack_app.to_s
+
+          # Check if engine's base controller inherits ApplicationController or includes MechaAuthorize
+          base_controller_name = "#{engine_name}::ApplicationController"
+          base_controller = base_controller_name.safe_constantize
+
+          if base_controller
+            inherits_app_ctrl = base_controller < ::ApplicationController
+            includes_mecha_auth = base_controller.ancestors.include?(MechaAuthorize::Controller)
+
+            unless inherits_app_ctrl || includes_mecha_auth
+              warnings << "Mounted engine #{engine_name} at #{route.path.spec} base controller #{base_controller_name} does not inherit ApplicationController or include MechaAuthorize::Controller."
+            end
+          end
+        end
+
+        warnings
+      end
+    end
+  end
+end

data/lib/mecha_authorize/configuration.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module MechaAuthorize
+  class Configuration
+    attr_accessor :config_path,
+                  :probe_header,
+                  :probe_status,
+                  :debug_colorization,
+                  :on_unauthorized,
+                  :test_personas,
+                  :test_setup,
+                  :test_teardown
+
+    def initialize
+      @config_path = defined?(Rails) && Rails.respond_to?(:root) && Rails.root ? Rails.root.join("config/mecha_authorize.yml") : "config/mecha_authorize.yml"
+      @probe_header = "X-Mecha-Authorize-Probe"
+      @probe_status = 251 # Special sentinel HTTP status (251 Verified)
+      @roles = {}
+      @debug_colorization = {
+        public: :green,
+        admin: :light_red,
+        user_ui: :light_purple,
+        user_api: :light_cyan,
+        none: :dark_grey
+      }
+      @on_unauthorized = ->(controller) { controller.send(:render_404) }
+      @test_personas = nil
+      @test_setup = nil
+      @test_teardown = nil
+    end
+
+    def define_role(name, &block)
+      @roles[name.to_sym] = block
+    end
+
+    def roles
+      @roles
+    end
+
+    def role_names
+      @roles.keys
+    end
+
+    def configure_test_matrix(personas: nil, setup: nil, teardown: nil)
+      @test_personas = personas if personas
+      @test_setup = setup if setup
+      @test_teardown = teardown if teardown
+    end
+  end
+end

data/lib/mecha_authorize/controller.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module MechaAuthorize
+  module Controller
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :authorize_route!
+    end
+
+    class_methods do
+      def authorization_routes
+        if defined?(@authorization_routes) && !@authorization_routes.nil?
+          @authorization_routes
+        elsif superclass.respond_to?(:authorization_routes) && superclass != ActionController::Base
+          superclass.authorization_routes
+        elsif defined?(AUTHORIZATION_ROUTES)
+          AUTHORIZATION_ROUTES
+        else
+          MechaAuthorize.matcher&.all_rules || {}
+        end
+      end
+
+      def authorization_routes=(routes)
+        @authorization_routes = routes
+      end
+    end
+
+    private
+
+    def authorize_route!
+      verb = extract_request_verb
+      path = request.path
+      route_uri_pattern = request.respond_to?(:route_uri_pattern) ? request.route_uri_pattern : nil
+
+      # If custom authorization_routes are set on the controller class (e.g. In isolated unit tests),
+      # evaluate against that custom dictionary; otherwise use the global MechaAuthorize.matcher.
+      custom_routes = self.class.authorization_routes
+      rule = if custom_routes && custom_routes != AUTHORIZATION_ROUTES && custom_routes != MechaAuthorize.matcher&.all_rules
+        match_custom_routes(verb, path, route_uri_pattern, custom_routes)
+      else
+        MechaAuthorize.matcher.match(verb, path, route_uri_pattern)
+      end
+
+      # 1. Closed-by-default: If no rule matches, deny access
+      if rule.nil?
+        render_unauthorized
+        return
+      end
+
+      # 2. Public bypass
+      if rule[:public]
+        if probe_request?
+          head MechaAuthorize.configuration.probe_status
+          return
+        end
+        return
+      end
+
+      # 3. Authentication requirement for non-public routes
+      unless logged_in?
+        render_unauthorized
+        return
+      end
+
+      # 4. Check permissions
+      has_access = check_role_access(rule)
+
+      unless has_access
+        render_unauthorized
+        return
+      end
+
+      # 5. Early return on probe requests with sentinel status
+      if probe_request?
+        head MechaAuthorize.configuration.probe_status and return
+      end
+    end
+
+    def extract_request_verb
+      if request.respond_to?(:request_method) && request.request_method.present?
+        request.request_method.to_s.upcase
+      elsif request.respond_to?(:raw_request_method) && request.raw_request_method.present?
+        request.raw_request_method.to_s.upcase
+      else
+        begin
+          v = request.method
+          v.is_a?(String) ? v.upcase : "GET"
+        rescue ArgumentError
+          "GET"
+        end
+      end
+    end
+
+    def probe_request?
+      header_name = MechaAuthorize.configuration.probe_header
+      val = nil
+      if request.respond_to?(:headers) && request.headers
+        val = request.headers[header_name]
+      end
+      if val.nil? && request.respond_to?(:get_header)
+        val = request.get_header("HTTP_#{header_name.upcase.tr('-', '_')}")
+      end
+      val == "1" || val == "true"
+    end
+
+    def check_role_access(rule)
+      user = current_user
+      roles = MechaAuthorize.configuration.roles
+
+      roles.any? do |role_name, resolver|
+        next false if role_name == :public
+        rule[role_name] && resolver.call(user, request)
+      end
+    end
+
+    def render_unauthorized
+      MechaAuthorize.configuration.on_unauthorized.call(self)
+    end
+
+    def current_user
+      nil
+    end
+
+    def logged_in?
+      respond_to?(:current_user, true) && !current_user.nil?
+    end
+
+    def match_custom_routes(verb, path, route_uri_pattern, routes_hash)
+      # Check compound key [verb, path]
+      key = [verb.to_s.upcase, path]
+      return routes_hash[key] if routes_hash.key?(key)
+
+      # Check wildcard verb ["*", path]
+      wildcard_verb_key = ["*", path]
+      return routes_hash[wildcard_verb_key] if routes_hash.key?(wildcard_verb_key)
+
+      # Check plain path key (legacy backward-compatibility for mocks)
+      return routes_hash[path] if routes_hash.key?(path)
+
+      # Check wildcards
+      routes_hash.each do |k, v|
+        pattern = k.is_a?(Array) ? k[1] : k
+        rule_verb = k.is_a?(Array) ? k[0] : "*"
+
+        next unless rule_verb == "*" || rule_verb == verb.to_s.upcase
+
+        if pattern.include?("*") && (
+          File.fnmatch(pattern, path) || (pattern.end_with?("/*") && path == pattern.delete_suffix("/*"))
+        )
+          return v
+        end
+      end
+
+      # Dynamic pattern fallback
+      if route_uri_pattern
+        clean_pat = route_uri_pattern.sub(/\(\.:format\)$/, "")
+        return routes_hash[[verb.to_s.upcase, clean_pat]] if routes_hash.key?([verb.to_s.upcase, clean_pat])
+        return routes_hash[["*", clean_pat]] if routes_hash.key?([clean_pat])
+        return routes_hash[clean_pat] if routes_hash.key?(clean_pat)
+        return routes_hash[route_uri_pattern] if routes_hash.key?(route_uri_pattern)
+      end
+
+      nil
+    end
+  end
+end

data/lib/mecha_authorize/matcher.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module MechaAuthorize
+  class Matcher
+    VALID_VERBS = %w[GET POST PUT PATCH DELETE HEAD OPTIONS *].freeze
+
+    attr_reader :routes, :indexed_routes, :wildcard_routes, :colorization
+
+    def initialize(config_path_or_hash = nil, role_names = %i[public admin user_ui user_api])
+      @role_names = role_names.map(&:to_sym)
+      @indexed_routes = {}
+      @wildcard_routes = []
+      @raw_routes = []
+      @colorization = {}
+
+      if config_path_or_hash.is_a?(Hash)
+        load_from_hash(config_path_or_hash)
+      elsif config_path_or_hash
+        load_from_file(config_path_or_hash)
+      end
+    end
+
+    def load_from_file(path)
+      raise "Authorization configuration file missing: #{path}" unless File.exist?(path)
+
+      data = begin
+        YAML.load_file(path)
+      rescue => e
+        raise "Invalid YAML syntax in #{path}: #{e.message}"
+      end
+
+      load_from_hash(data)
+    end
+
+    def load_from_hash(data)
+      unless data.is_a?(Hash) && data.key?("routes") && data["routes"].is_a?(Array)
+        raise "Authorization config must have a top-level 'routes' list"
+      end
+
+      @raw_routes = data["routes"]
+      @indexed_routes = {}
+      @wildcard_routes = []
+
+      @raw_routes.each_with_index do |route, idx|
+        validate_route_entry!(route, idx)
+        register_route_entry(route)
+      end
+
+      if data["debug_colorization"].is_a?(Hash)
+        @colorization = data["debug_colorization"].transform_keys(&:to_sym).transform_values { |v| v.to_s.sub(/^:/, "").to_sym }
+      end
+
+      @indexed_routes.freeze
+      @wildcard_routes.freeze
+      self
+    end
+
+    # Match incoming request by HTTP verb and path
+    def match(verb, path, route_uri_pattern = nil)
+      v = (verb || "GET").to_s.upcase
+      clean_path = path.to_s.sub(/\(\.:format\)$/, "")
+
+      # 1. Exact match [verb, path]
+      rule = @indexed_routes[[v, clean_path]]
+      return rule if rule
+
+      # Fallback for HEAD -> GET
+      if v == "HEAD" && (head_rule = @indexed_routes[["GET", clean_path]])
+        return head_rule
+      end
+
+      # 2. Match [wildcard_verb "*", path]
+      wildcard_verb_rule = @indexed_routes[["*", clean_path]]
+      return wildcard_verb_rule if wildcard_verb_rule
+
+      # 3. Path wildcards (e.g. /admin/*)
+      @wildcard_routes.each do |w|
+        next unless w[:verb] == "*" || w[:verb] == v || (v == "HEAD" && w[:verb] == "GET")
+
+        pattern = w[:pattern]
+        if File.fnmatch(pattern, clean_path) || (pattern.end_with?("/*") && clean_path == pattern.delete_suffix("/*"))
+          return w[:rule]
+        end
+      end
+
+      # 4. Rails dynamic route URI pattern fallback (e.g. /emails/:id/thread)
+      if route_uri_pattern
+        clean_pattern = route_uri_pattern.to_s.sub(/\(\.:format\)$/, "")
+        rule = @indexed_routes[[v, clean_pattern]] || (v == "HEAD" && @indexed_routes[["GET", clean_pattern]]) || @indexed_routes[["*", clean_pattern]]
+        return rule if rule
+      end
+
+      # 5. Regex parameterized fallback (matches paths like /auth/google_oauth2/callback to /auth/:provider/callback)
+      regex_rule = match_by_pattern_regex(v, clean_path)
+      return regex_rule if regex_rule
+
+      nil
+    end
+
+    # Helper for static matching and route inspection: finds if a route specification matches
+    def match_route_spec(verb, pattern)
+      v = (verb || "GET").to_s.upcase
+      clean_pattern = pattern.to_s.sub(/\(\.:format\)$/, "")
+
+      # Exact match
+      rule = @indexed_routes[[v, clean_pattern]] || @indexed_routes[["*", clean_pattern]]
+      return rule if rule
+
+      # Wildcard path check
+      @wildcard_routes.each do |w|
+        next unless w[:verb] == "*" || w[:verb] == v
+
+        if File.fnmatch(w[:pattern], clean_pattern) || (w[:pattern].end_with?("/*") && clean_pattern.start_with?(w[:pattern].delete_suffix("/*")))
+          return w[:rule]
+        end
+      end
+
+      # Reverse regex matching: check if clean_pattern matches any indexed route pattern
+      @indexed_routes.each do |(rule_verb, rule_pattern), r|
+        next unless rule_verb == "*" || rule_verb == v
+        next unless rule_pattern.include?(":")
+
+        regex = pattern_to_regex(rule_pattern)
+        return r if regex.match?(clean_pattern)
+      end
+
+      # Forward regex matching: check if any indexed pattern matches clean_pattern (e.g., /auth/:provider/callback vs /auth/google_oauth2)
+      if clean_pattern.include?(":")
+        spec_regex = pattern_to_regex(clean_pattern)
+        @indexed_routes.each do |(rule_verb, rule_pattern), r|
+          next unless rule_verb == "*" || rule_verb == v
+          return r if spec_regex.match?(rule_pattern)
+        end
+      end
+
+      nil
+    end
+
+    def all_rules
+      @indexed_routes
+    end
+
+    private
+
+    def validate_route_entry!(route, idx)
+      unless route.is_a?(Hash)
+        raise "Authorization route at index #{idx} is not a hash"
+      end
+
+      pattern = route["route_pattern"]
+      unless pattern.is_a?(String) && !pattern.strip.empty? && pattern.start_with?("/")
+        raise "Authorization route at index #{idx} must have a non-empty string starting with '/' for 'route_pattern'"
+      end
+
+      verbs = extract_verbs(route)
+      if verbs.empty?
+        raise "Authorization route '#{pattern}' at index #{idx} must explicitly define 'verb' or 'verbs'"
+      end
+
+      verbs.each do |verb|
+        unless VALID_VERBS.include?(verb.upcase)
+          raise "Authorization route '#{pattern}' key 'verb' has invalid HTTP verb '#{verb}'. Allowed verbs: #{VALID_VERBS.join(', ')}"
+        end
+      end
+
+      @role_names.each do |role|
+        val = route[role.to_s]
+        unless val == true || val == false
+          raise "Authorization route '#{pattern}' key '#{role}' must be a boolean (true or false), got #{val.inspect}"
+        end
+      end
+    end
+
+    def extract_verbs(route)
+      if route.key?("verbs") && route["verbs"].is_a?(Array)
+        route["verbs"].map { |v| v.to_s.strip.upcase }
+      elsif route.key?("verb") && route["verb"].is_a?(String)
+        [route["verb"].to_s.strip.upcase]
+      else
+        []
+      end
+    end
+
+    def register_route_entry(route)
+      pattern = route["route_pattern"]
+      verbs = extract_verbs(route)
+
+      rule = @role_names.each_with_object({}) do |role, h|
+        h[role] = route[role.to_s]
+      end.freeze
+
+      verbs.each do |verb|
+        key = [verb, pattern]
+        @indexed_routes[key] = rule
+
+        if pattern.include?("*")
+          @wildcard_routes << {
+            verb: verb,
+            pattern: pattern,
+            rule: rule
+          }
+        end
+      end
+    end
+
+    def pattern_to_regex(pattern)
+      segments = pattern.split("/", -1)
+      regex_segments = segments.map do |seg|
+        if seg.start_with?(":")
+          "[^/]+"
+        elsif seg.start_with?("*")
+          ".*"
+        else
+          Regexp.escape(seg)
+        end
+      end
+      Regexp.new("\\A#{regex_segments.join('/')}\\z")
+    end
+
+    def match_by_pattern_regex(verb, path)
+      @indexed_routes.each do |(rule_verb, rule_pattern), rule|
+        next unless rule_verb == "*" || rule_verb == verb || (verb == "HEAD" && rule_verb == "GET")
+        next unless rule_pattern.include?(":")
+
+        regex = pattern_to_regex(rule_pattern)
+        return rule if regex.match?(path)
+      end
+      nil
+    end
+  end
+end

data/lib/mecha_authorize/matrix_test.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+unless defined?(ActionDispatch::IntegrationTest)
+  app_test_helper = File.join(Dir.pwd, "test/test_helper.rb")
+  require app_test_helper if File.exist?(app_test_helper)
+end
+require "mecha_authorize"
+
+module MechaAuthorize
+  class MatrixTest < ActionDispatch::IntegrationTest
+    setup do
+      if MechaAuthorize.configuration.test_setup
+        instance_exec(&MechaAuthorize.configuration.test_setup)
+      end
+    end
+
+    teardown do
+      if MechaAuthorize.configuration.test_teardown
+        instance_exec(&MechaAuthorize.configuration.test_teardown)
+      end
+    end
+
+    test "static route authorization audit passes with zero dead rules and zero engine bypasses" do
+      result = MechaAuthorize::Auditor::Static.new.audit
+
+      assert_empty result.dead_rules, "Found dead/stale rules in mecha_authorize.yml: #{result.dead_rules.inspect}"
+      assert_empty result.engine_warnings, "Found engine bypass warnings: #{result.engine_warnings.inspect}"
+      assert result.mapped_routes.any?, "Expected routes to be mapped to authorization rules"
+    end
+
+    test "unmapped routes strictly return 404 for all personas" do
+      get "/unmapped_nonexistent_test_route", headers: { MechaAuthorize.configuration.probe_header => "1" }
+      assert_response :not_found
+
+      get "/unmapped_nonexistent_test_route"
+      assert_response :not_found
+    end
+
+    test "wrong HTTP verb strictly returns 404 closed-by-default" do
+      delete "/login", headers: { MechaAuthorize.configuration.probe_header => "1" }
+      assert_response :not_found
+    end
+
+    def self.define_route_matrix_tests!
+      return if @route_matrix_tests_defined
+
+      routes = MechaAuthorize::Auditor::Prober.collect_prober_routes
+      return if routes.empty?
+
+      @route_matrix_tests_defined = true
+
+      routes.each do |route_info|
+        verb = route_info[:verb]
+        raw_path = route_info[:path]
+
+        test "behavioral persona matrix probe for #{verb} #{raw_path}" do
+          personas_proc = MechaAuthorize.configuration.test_personas
+          assert_not_nil personas_proc, "MechaAuthorize.configuration.test_personas must be configured for behavioral matrix testing"
+
+          prober = MechaAuthorize::Auditor::Prober.new(self)
+          personas = instance_exec(&personas_proc)
+          result = prober.probe_route(route_info, personas)
+
+          assert result.success?, "Prober failed for #{verb} #{raw_path}:\n" +
+            result.failures.map { |f| "  - #{f.route} [#{f.persona}]: #{f.message}" }.join("\n")
+        end
+      end
+    end
+
+    define_route_matrix_tests!
+  end
+end

data/lib/mecha_authorize/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module MechaAuthorize
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load File.expand_path("../tasks/mecha_authorize.rake", __dir__)
+    end
+  end
+end

data/lib/mecha_authorize/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module MechaAuthorize
+  VERSION = "0.1.0"
+  Version = VERSION
+end

data/lib/mecha_authorize.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "mecha_authorize/version"
+require_relative "mecha_authorize/configuration"
+require_relative "mecha_authorize/matcher"
+require_relative "mecha_authorize/controller"
+require_relative "mecha_authorize/auditor/static"
+require_relative "mecha_authorize/auditor/prober"
+require_relative "mecha_authorize/railtie" if defined?(Rails::Railtie)
+
+module MechaAuthorize
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration) if block_given?
+      reload!
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+      @matcher = nil
+    end
+
+    def matcher
+      @matcher ||= Matcher.new(configuration.config_path, configuration.role_names)
+    end
+
+    def reload!
+      @matcher = Matcher.new(configuration.config_path, configuration.role_names)
+    end
+  end
+end

data/lib/tasks/mecha_authorize.rake

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "tiny_color"
+require_relative "../mecha_authorize"
+
+class String
+  def dark_grey
+    respond_to?(:grey) ? grey : self
+  end unless method_defined?(:dark_grey)
+
+  def dark_gray
+    respond_to?(:gray) ? gray : self
+  end unless method_defined?(:dark_gray)
+end
+
+desc "Print all routes and their MechaAuthorize authorization controls"
+task mecha_authorize: :environment do
+  routes = Rails.application.routes.routes.map { |r| ActionDispatch::Routing::RouteWrapper.new(r) }.reject(&:internal?)
+
+  all_mapped_routes = []
+
+  routes.each do |r|
+    if r.engine?
+      engine_routes = r.rack_app.routes
+      engine_routes = engine_routes.routes if engine_routes.is_a?(ActionDispatch::Routing::RouteSet)
+
+      clean_mount = r.path.sub("(.:format)", "").sub("/*path", "").sub("/*filename", "").chomp("/")
+
+      engine_routes.map { |er| ActionDispatch::Routing::RouteWrapper.new(er) }.reject(&:internal?).each do |er|
+        full_path = "#{clean_mount}#{er.path}".sub("(.:format)", "")
+        verb = er.verb.to_s.empty? ? "*" : er.verb.to_s.upcase
+        all_mapped_routes << { verb: verb, path: full_path }
+      end
+    else
+      verb = r.verb.to_s.empty? ? "*" : r.verb.to_s.upcase
+      all_mapped_routes << { verb: verb, path: r.path.sub("(.:format)", "") }
+    end
+  end
+
+  matcher = MechaAuthorize.matcher
+  colors = MechaAuthorize.configuration.debug_colorization
+
+  colorize_char = ->(char, perm) {
+    return char if char == "." && perm != :none
+    color = colors[perm]
+    if color && char.respond_to?(color)
+      char.send(color)
+    else
+      char
+    end
+  }
+
+  max_verb_len = all_mapped_routes.map { |r| r[:verb].to_s.length }.max || 4
+  max_verb_len = [max_verb_len, 4].max
+
+  max_path_len = all_mapped_routes.map { |r| r[:path].to_s.length }.max || 11
+  max_path_len = [max_path_len, 11].max
+
+  puts sprintf("%-#{max_verb_len}s %-#{max_path_len}s %s", "Verb", "URI Pattern", "Access")
+
+  all_mapped_routes.each do |r|
+    rule = matcher.match_route_spec(r[:verb], r[:path])
+
+    has_access = rule && (rule[:public] || rule[:admin] || rule[:user_ui] || rule[:user_api])
+
+    if has_access
+      public_char  = rule[:public] ? "P" : "."
+      admin_char   = rule[:admin] ? "A" : "."
+      user_ui_char = rule[:user_ui] ? "U" : "."
+      user_api_char = rule[:user_api] ? "X" : "."
+
+      color_to_apply = if rule[:public]
+        colors[:public]
+      elsif rule[:admin]
+        colors[:admin]
+      elsif rule[:user_ui]
+        colors[:user_ui]
+      elsif rule[:user_api]
+        colors[:user_api]
+      end
+
+      public_colorized   = colorize_char.call(public_char, :public)
+      admin_colorized    = colorize_char.call(admin_char, :admin)
+      user_ui_colorized  = colorize_char.call(user_ui_char, :user_ui)
+      user_api_colorized = colorize_char.call(user_api_char, :user_api)
+    else
+      public_char  = "."
+      admin_char   = "."
+      user_ui_char = "."
+      user_api_char = "."
+
+      color_to_apply = colors[:none]
+
+      public_colorized   = colorize_char.call(public_char, :none)
+      admin_colorized    = colorize_char.call(admin_char, :none)
+      user_ui_colorized  = colorize_char.call(user_ui_char, :none)
+      user_api_colorized = colorize_char.call(user_api_char, :none)
+    end
+
+    padded_path = sprintf("%-#{max_path_len}s", r[:path])
+    path_colorized = if color_to_apply && padded_path.respond_to?(color_to_apply)
+      padded_path.send(color_to_apply)
+    else
+      padded_path
+    end
+
+    access_string = "#{public_colorized}#{admin_colorized}#{user_ui_colorized}#{user_api_colorized}"
+    puts sprintf("%-#{max_verb_len}s %s %s", r[:verb], path_colorized, access_string)
+  end
+end
+
+namespace :mecha_authorize do
+  namespace :verify do
+    desc "Statically verify route authorization parity, dead rules, and engine protection"
+    task static: :environment do
+      puts "Running MechaAuthorize static route audit..."
+      auditor = MechaAuthorize::Auditor::Static.new
+      result = auditor.audit
+
+      puts "  -> #{result.mapped_routes.size} routes mapped to explicit authorization rules"
+
+      if result.unmapped_routes.any?
+        puts "  -> #{result.unmapped_routes.size} unmapped routes (defaulting to closed-by-default 404):"
+        result.unmapped_routes.each do |r|
+          puts "     [404] #{r[:verb]} #{r[:path]}"
+        end
+      end
+
+      if result.dead_rules.any?
+        puts "\nERROR: Found #{result.dead_rules.size} dead/stale rule(s) in mecha_authorize.yml:".light_red
+        result.dead_rules.each do |dr|
+          puts "  - #{dr[:verb]} #{dr[:pattern]}"
+        end
+      end
+
+      if result.engine_warnings.any?
+        puts "\nWARNING: Mounted engine bypass warning(s):".light_red
+        result.engine_warnings.each do |w|
+          puts "  - #{w}"
+        end
+      end
+
+      if result.success?
+        puts "\n✓ Static route authorization audit passed: 0 dead rules, 0 engine bypasses.".green
+      else
+        abort("\n✗ Static route authorization audit failed. Please prune dead rules or resolve engine bypasses.")
+      end
+    end
+
+    desc "Run behavioral persona matrix test suite"
+    task behavioral: :environment do
+      puts "Running MechaAuthorize behavioral persona matrix test suite..."
+      matrix_test_path = File.expand_path("../mecha_authorize/matrix_test.rb", __dir__)
+      system({ "MECHA_MATRIX_STANDALONE" => "1" }, "bin/rails", "test", matrix_test_path) || abort("Behavioral verification failed.")
+    end
+  end
+
+  desc "Run both static parity and behavioral persona verification"
+  task verify: %w[verify:static verify:behavioral]
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: mecha_authorize
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jeff Lunt
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: tiny_color
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: MechaAuthorize provides a YAML-driven, closed-by-default route authorization
+  system for Rails applications, complete with static route parity auditing and behavioral
+  persona matrix probing.
+email:
+- jefflunt@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- lib/mecha_authorize.rb
+- lib/mecha_authorize/auditor/prober.rb
+- lib/mecha_authorize/auditor/static.rb
+- lib/mecha_authorize/configuration.rb
+- lib/mecha_authorize/controller.rb
+- lib/mecha_authorize/matcher.rb
+- lib/mecha_authorize/matrix_test.rb
+- lib/mecha_authorize/railtie.rb
+- lib/mecha_authorize/version.rb
+- lib/tasks/mecha_authorize.rake
+homepage: https://github.com/jefflunt/mecha_authorize
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Closed-by-default route authorization and auditing for Rails
+test_files: []