current_scope 0.2.0

data/lib/generators/current_scope/install/install_generator.rb

@@ -0,0 +1,33 @@
+module CurrentScope
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def copy_initializer
+        template "initializer.rb", "config/initializers/current_scope.rb"
+      end
+
+      def mount_engine
+        route 'mount CurrentScope::Engine => "/current_scope"'
+      end
+
+      def show_next_steps
+        say <<~NEXT
+
+          CurrentScope installed. Next steps:
+
+            1. bin/rails current_scope:install:migrations && bin/rails db:migrate
+            2. Include the concerns in ApplicationController (Context first):
+                 include CurrentScope::Context
+                 include CurrentScope::Guard
+            3. Seed the baseline roles and give yourself full access, e.g. in db/seeds.rb:
+                 CurrentScope.seed_defaults!
+                 CurrentScope::RoleAssignment.create!(
+                   subject: User.first, role: CurrentScope::Role.find_by!(name: "Owner"))
+            4. Manage roles at /current_scope (full-access subjects only).
+
+        NEXT
+      end
+    end
+  end
+end

data/lib/generators/current_scope/install/templates/initializer.rb

@@ -0,0 +1,77 @@
+CurrentScope.configure do |config|
+  # Controller method that returns the authenticated subject.
+  # config.user_method = :current_user
+
+  # Class whose instances hold roles, used by the management UI.
+  # config.subject_class = "User"
+
+  # How a subject is identified in the management UI (an id is meaningless with
+  # UUID keys). A Symbol names a method; a Proc takes the subject. Defaults to a
+  # best-effort label (current_scope_label, else name/email/title, else id).
+  # config.subject_label = :email
+  # config.subject_label = ->(u) { "#{u.first_name} #{u.last_name}" }
+
+  # Fold the role-editor grid's action columns. Default = CRUD (new/edit hide
+  # into create/update; index+show read as one). Set to nil to show every raw
+  # action as its own column.
+  # config.permission_grid_groups = { "read" => %w[index show], "create" => %w[new create],
+  #                                   "update" => %w[edit update], "destroy" => %w[destroy] }
+
+  # --- Impersonation (act-as) ---------------------------------------------
+  # These three knobs layer, in this order:
+  #
+  #   1. actor_method                        — turns impersonation ON.
+  #   2. allow_mutations_while_impersonating — the read-only gate runs FIRST.
+  #   3. sod_identity                        — only observable once a mutation
+  #                                            is allowed through (or on a
+  #                                            GET-listed sod_action).
+  #
+  # Controller method returning the REAL actor while impersonating. Leave unset
+  # when no one impersonates — actor then equals the subject, so attribution
+  # reads current_scope_actor with no nil branch, and sod_identity below has no
+  # effect. See the "Impersonation (act-as)" section of the README.
+  # config.actor_method = :true_user
+
+  # false (default): an impersonated session is read-only — every non-GET/HEAD
+  # request is denied, INCLUDING the engine's management UI. Your
+  # stop-impersonation, sign-out, and sign-in endpoints must opt out with
+  # skip_before_action :current_scope_mutation_guard!, or impersonation (and
+  # sign-in) can never clear it.
+  # config.allow_mutations_while_impersonating = false
+
+  # Which identities the separation-of-duties veto weighs. :either (default)
+  # also vetoes a record the REAL actor initiated while impersonating, so
+  # impersonation can never approve your own record. :subject weighs only the
+  # effective subject. Identical when not impersonating.
+  # config.sod_identity = :either
+  # ------------------------------------------------------------------------
+
+  # Separation of duties is OPT-IN — empty by default. List the actions a
+  # record's initiator can never perform on their own record (four-eyes).
+  # Deliberately NOT editable in the UI. Records reached by these actions must
+  # define current_scope_initiator (return nil to exempt a record type) — the
+  # resolver raises if the hook is missing. Leave commented for RBAC-only apps.
+  # config.sod_actions = %w[approve]
+
+  # Audit ledger — tri-state: false | true (default) | :strict.
+  #   false   — no audit rows recorded.
+  #   true    — record every authorization change; if the events table hasn't
+  #             been migrated yet, degrade gracefully (skip + warn once).
+  #   :strict — a missing events table RAISES (rolling the mutation back), so an
+  #             audit-mandatory app never commits an unaudited change.
+  # config.audit = true
+
+  # Dev/test aid: log a nudge when an SoD action is ALLOWED but was gated with a
+  # nil record — i.e. the SoD veto was silently skipped because
+  # current_scope_record returned nil on a member action. Off by default; never
+  # changes behavior.
+  # config.warn_on_nil_sod_record = false
+
+  # Controller paths (regexps) excluded from the permission grid. Excluded
+  # controllers can't be granted, so they must also skip the gate with
+  # skip_before_action :current_scope_check! — Guard raises otherwise.
+  # config.excluded_controllers += [%r{\Awebhooks/}]
+
+  # Controller the management UI inherits from (for host auth + before_actions).
+  # config.parent_controller = "::ApplicationController"
+end

data/lib/tasks/current_scope_tasks.rake

@@ -0,0 +1,15 @@
+namespace :current_scope do
+  desc "Grant the full-access Owner role to a subject (bootstrap the first admin). " \
+       "Usage: bin/rails current_scope:grant SUBJECT_ID=1"
+  task grant: :environment do
+    id = ENV["SUBJECT_ID"]
+    abort "SUBJECT_ID is required, e.g. bin/rails current_scope:grant SUBJECT_ID=1" if id.blank?
+
+    klass = CurrentScope.config.subject_class.constantize
+    subject = klass.find_by(id: id)
+    abort "No #{klass} with id=#{id}" if subject.nil?
+
+    CurrentScope.grant!(subject)
+    puts "Granted the full-access Owner role to #{klass}##{subject.id}."
+  end
+end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: current_scope
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- David Teren
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: 'A mountable Rails engine for authorization: permissions auto-derived
+  from controller actions, roles as editable data, per-record scoped roles, a separation-of-duties
+  veto, and an ambient authorization context that makes allowed_to? work identically
+  in controllers, views, and components.'
+email:
+- dteren@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/javascripts/current_scope/application.js
+- app/assets/stylesheets/current_scope/application.css
+- app/controllers/current_scope/application_controller.rb
+- app/controllers/current_scope/events_controller.rb
+- app/controllers/current_scope/role_assignments_controller.rb
+- app/controllers/current_scope/roles_controller.rb
+- app/controllers/current_scope/scoped_role_assignments_controller.rb
+- app/controllers/current_scope/subjects_controller.rb
+- app/helpers/current_scope/application_helper.rb
+- app/models/current_scope/application_record.rb
+- app/models/current_scope/current.rb
+- app/models/current_scope/event.rb
+- app/models/current_scope/role.rb
+- app/models/current_scope/role_assignment.rb
+- app/models/current_scope/role_permission.rb
+- app/models/current_scope/scoped_role_assignment.rb
+- app/views/current_scope/events/index.html.erb
+- app/views/current_scope/roles/edit.html.erb
+- app/views/current_scope/roles/index.html.erb
+- app/views/current_scope/roles/members.html.erb
+- app/views/current_scope/roles/new.html.erb
+- app/views/current_scope/scoped_role_assignments/new.html.erb
+- app/views/current_scope/subjects/index.html.erb
+- app/views/layouts/current_scope/application.html.erb
+- config/routes.rb
+- db/migrate/20260710000001_create_current_scope_tables.rb
+- db/migrate/20260710000002_create_current_scope_events.rb
+- db/migrate/20260714000001_add_description_to_current_scope_roles.rb
+- lib/current_scope.rb
+- lib/current_scope/configuration.rb
+- lib/current_scope/context.rb
+- lib/current_scope/engine.rb
+- lib/current_scope/gating_tripwire.rb
+- lib/current_scope/guard.rb
+- lib/current_scope/mutation_guard.rb
+- lib/current_scope/permission_catalog.rb
+- lib/current_scope/permission_grid.rb
+- lib/current_scope/permissions.rb
+- lib/current_scope/resolver.rb
+- lib/current_scope/scopeable.rb
+- lib/current_scope/test_helpers.rb
+- lib/current_scope/version.rb
+- lib/generators/current_scope/install/install_generator.rb
+- lib/generators/current_scope/install/templates/initializer.rb
+- lib/tasks/current_scope_tasks.rake
+homepage: https://github.com/davidteren/current_scope
+licenses:
+- MIT
+metadata:
+  changelog_uri: https://github.com/davidteren/current_scope/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Data-driven authorization for Rails with an ambient current-user context.
+test_files: []