permission_forge 0.14.1

data/config/routes.rb

@@ -0,0 +1,143 @@
+PermissionForge::Engine.routes.draw do
+  # Engine-served CSS/JS/brand files — no host asset pipeline required.
+  get 'pf-assets/:file', to: 'assets#show', as: :pf_asset, constraints: { file: /[\w.-]+/ }, format: false
+
+  root to: 'home#index'
+
+  # Per-browser admin preferences (theme, dismissed helper banners).
+  resource :preferences, only: :update
+
+  get 'settings', to: 'settings#show', as: :settings
+  get 'field_lookup', to: 'field_lookups#show', as: :field_lookup
+
+  # The audit log (read-only): the filtered log and its CSV / JSON export, one
+  # event by uuid, and the "who holds what" export.
+  resources :audit_events, path: 'audit', only: %i[index show] do
+    collection do
+      get :holdings
+    end
+  end
+
+  # Home "needs attention": remove expired assignments (dry run shown inline on Home).
+  delete 'maintenance/cleanup', to: 'maintenance#cleanup', as: :maintenance_cleanup
+
+  resources :people, only: %i[index show] do
+    member do
+      get :remove_all, action: :confirm_remove_all
+      delete :remove_all
+      post :refresh_cache
+      get :consent, action: :consent_preview
+      post :consent, action: :withdraw_consent
+      get :erasure, action: :erasure_preview
+      post :erasure, action: :erase
+    end
+  end
+
+  resources :assignments, only: %i[new create update destroy] do
+    member do
+      get :remove, action: :confirm_destroy
+      post :keep
+    end
+    collection do
+      post :restore
+      post :undo
+    end
+  end
+
+  resources :permission_sets, only: %i[index new create show destroy] do
+    member do
+      post :review
+      patch :apply
+      post :duplicate
+      get :delete, action: :confirm_destroy
+      get :switch_mode, action: :confirm_switch_mode
+      patch :switch_mode
+      patch :conditions
+    end
+
+    resource :bulk_assignment, only: %i[new create] do
+      post :preview
+      get :revoke, action: :confirm_revoke
+      delete :revoke
+    end
+
+    resources :resources, param: :model, only: %i[new create show destroy],
+                          constraints: { model: %r{[^/]+} } do
+      member do
+        post :review
+        patch :apply
+        post :sync
+        get :delete, action: :confirm_destroy
+      end
+
+      resources :fields, controller: 'resource_fields', param: :key, only: %i[show update],
+                         constraints: { key: %r{[^/]+} } do
+        member do
+          post :acknowledge
+          post :apply_recommendation
+        end
+      end
+      resources :actions, controller: 'resource_actions', only: %i[new create show update destroy] do
+        member do
+          get :delete, action: :confirm_destroy
+        end
+      end
+      resources :rules, controller: 'permission_set_rules', only: %i[new create edit update destroy] do
+        collection do
+          post :refresh
+        end
+        member do
+          patch :toggle
+          get :delete, action: :confirm_destroy
+        end
+      end
+    end
+  end
+
+  resources :groups, controller: 'permission_set_groups', only: %i[index create show update destroy] do
+    member do
+      post :duplicate
+      get :delete, action: :confirm_destroy
+      post :add_set
+      delete :remove_set
+    end
+    resources :members, controller: 'permission_set_group_users', only: %i[create destroy]
+  end
+
+  # JSON Admin API — routes are always drawn; access is guarded at runtime
+  # by BaseController checking api_enabled + api_auth configuration.
+  namespace :api, defaults: { format: :json } do
+    resource :stats, only: [:show], controller: 'dashboard'
+
+    # The audit log is read-only over the API: no write route exists.
+    resources :audit_events, only: %i[index show], param: :identifier
+
+    resources :permission_sets, param: :identifier do
+      member do
+        post :clone
+      end
+
+      resources :resources, param: :identifier do
+        member do
+          post :generate_fields
+        end
+        resources :fields, param: :identifier, controller: 'resource_fields'
+        resources :actions, param: :identifier, controller: 'resource_actions'
+        resources :rules, param: :identifier, controller: 'permission_set_rules'
+      end
+
+      resources :users, param: :identifier, controller: 'permission_set_users', only: %i[index create destroy] do
+        collection do
+          post :bulk
+        end
+      end
+    end
+
+    resources :permission_set_groups, param: :identifier do
+      member do
+        post :clone
+      end
+      resources :users, param: :identifier, controller: 'permission_set_group_users', only: %i[index create destroy]
+    end
+  end
+end

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

@@ -0,0 +1,105 @@
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module PermissionForge
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      class_option :skip_migration, type: :boolean, default: false,
+                                    desc: 'Skip migration generation (for existing tables)'
+      class_option :table_prefix, type: :string, default: 'permission_forge_',
+                                  desc: 'Table name prefix for all permission_forge tables'
+      class_option :tenant, type: :string, default: nil,
+                            desc: 'Tenant model name for acts_as_tenant (e.g., Account)'
+      class_option :user_id_type, type: :string, default: nil,
+                                  desc: 'Column type for user ids: bigint, integer, uuid or string ' \
+                                        '(default: the primary key type of the configured user model)'
+      class_option :tenant_id_type, type: :string, default: nil,
+                                    desc: 'Column type for the tenant column ' \
+                                          '(default: the primary key type of the --tenant model)'
+
+      KEY_TYPES = %w[bigint integer uuid string].freeze
+      DETECTED_KEY_TYPES = { integer: 'bigint', uuid: 'uuid', string: 'string' }.freeze
+
+      def copy_initializer
+        template 'initializer.rb.tt', 'config/initializers/permission_forge.rb'
+      end
+
+      def copy_migration
+        return if options[:skip_migration]
+
+        migration_template 'migration.rb.tt', 'db/migrate/create_permission_forge_tables.rb'
+      end
+
+      private
+
+      def table_prefix
+        options[:table_prefix]
+      end
+
+      def tenant_model
+        options[:tenant].presence
+      end
+
+      # 'Account' and 'Billing::Account' both map to account_id — the column
+      # name cannot carry a namespace.
+      def tenant_column
+        return nil unless tenant_model
+
+        "#{tenant_model.demodulize.underscore}_id"
+      end
+
+      # Columns that store a host primary key (user ids, audit user ids, the
+      # tenant id) take the type of that key. A bigint column silently
+      # truncates a UUID to its leading digits, which makes different users
+      # (or tenants) share permission data.
+      def user_id_type
+        @user_id_type ||= key_type(options[:user_id_type], PermissionForge.configuration.user_class, '--user-id-type')
+      end
+
+      def tenant_id_type
+        return 'bigint' unless tenant_model
+
+        @tenant_id_type ||= key_type(options[:tenant_id_type], tenant_model, '--tenant-id-type')
+      end
+
+      def key_type(explicit, model_name, flag)
+        return validated_key_type(explicit, flag) if explicit.present?
+
+        detected_key_type(model_name) || assume_bigint(model_name, flag)
+      end
+
+      def validated_key_type(type, flag)
+        return type if KEY_TYPES.include?(type)
+
+        raise Thor::Error, "#{flag} must be one of #{KEY_TYPES.join(', ')} (got #{type.inspect})"
+      end
+
+      # nil when the model is not loadable, has no table yet, or has a
+      # composite primary key.
+      def detected_key_type(model_name)
+        model = model_name.to_s.safe_constantize
+        return unless model.respond_to?(:columns_hash)
+
+        primary_key = model.primary_key
+        column = model.columns_hash[primary_key] if primary_key.is_a?(String)
+        DETECTED_KEY_TYPES[column&.type]
+      rescue ActiveRecord::ActiveRecordError
+        nil
+      end
+
+      def assume_bigint(model_name, flag)
+        say_status :warning, "could not read the primary key type of #{model_name}; assuming bigint. " \
+                             "Pass #{flag}=uuid (or string) if its keys are not integers.", :yellow
+        'bigint'
+      end
+
+      def migration_version
+        "[#{ActiveRecord::Migration.current_version}]"
+      end
+    end
+  end
+end

data/lib/generators/permission_forge/install/templates/initializer.rb.tt

@@ -0,0 +1,148 @@
+# PermissionForge — the options you are most likely to set. Every option, its
+# default and what it does:
+#   https://github.com/fetijashari/permission_forge/blob/main/docs/configuration.md
+# Before production, go through the Production hardening checklist
+# (https://github.com/fetijashari/permission_forge#production-hardening-checklist);
+# `bin/rails permission_forge:audit` reports what is still open.
+PermissionForge.configure do |config|
+  # ---------------------------------------------------------------------------
+  # Closed for new installs (the library defaults stay open for existing apps)
+  # ---------------------------------------------------------------------------
+  # A guarded controller action (ControllerActionGuard) with nobody signed in is refused.
+  config.action_guard_nil_user_strategy = :deny
+  # Conditional Permission Sets fail closed without a request context (see below).
+  config.conditional_sets_strict_mode = true
+  # The cache is Rails.cache: use a shared store in production (Redis, Solid Cache, Memcached).
+  config.cache_backend = :rails_cache
+
+  # config.preset = :strict closes every fail-open default at once
+  # (docs/configuration.md#presets; a setting you make here still wins):
+  #   nil_user_strategy = :deny, auto_query_scoping = :filter_only,
+  #   response_filter_nil_user_strategy = :block, unconfigured_action_strategy = :block,
+  #   mask_virtual_attributes = :auto, extra_fields_default_access = :unconfigured,
+  #   and the three settings above.
+  # What it costs: with nil_user_strategy :deny and auto_query_scoping :filter_only,
+  # code that runs with no current user (jobs, mailers, seeds, webhooks, the
+  # console, sign-in lookups on a user model that includes PermissionScopedFindable)
+  # sees no protected rows, and a belongs_to presence check on a protected parent
+  # fails ("must exist"). Run such code with a user, or inside
+  # PermissionForge.without_permission_scope { }, where nobody signed in gets no rules:
+  # never around code an anonymous request reaches. Never include PermissionScopedFindable in the user model.
+  # config.preset = :strict
+
+  # ---------------------------------------------------------------------------
+  # Who is signed in
+  # ---------------------------------------------------------------------------
+  # The class name of your User model (string, lazily constantized), and the
+  # class that created_by / updated_by point to.
+  config.user_class = 'User'
+  config.audit_user_class = 'User'
+
+  # Returns the signed-in user, or nil. As generated it reads Current.user when
+  # the app has a Current class that answers `user` (Rails 8's authentication
+  # generator creates one) and nil otherwise: until you wire it, nobody is
+  # signed in.
+  config.current_user_resolver = -> { ::Current.user if defined?(::Current) && ::Current.respond_to?(:user) }
+
+  # Whether a user is active. It does not remove access: the audit task
+  # reports the assignments still held by users it calls inactive.
+  config.user_active_check = ->(user) { user.respond_to?(:active_for_authentication?) ? user.active_for_authentication? : true }
+
+  # The profile cached with each user's permissions (uuid: nil when users have none).
+  config.profile_builder = ->(user) {
+    { id: user.id, uuid: user.try(:uuid), name: user.try(:name), email: user.try(:email) }
+  }
+
+  # Prefix of the PermissionForge tables ('' for none).
+  config.table_name_prefix = '<%= table_prefix %>'
+
+  # ---------------------------------------------------------------------------
+  # Multi-tenancy (optional, requires the acts_as_tenant gem)
+  # ---------------------------------------------------------------------------
+  # Every PermissionForge table needs the tenant column (the install migration
+  # adds it with --tenant=Account). Boot fails if this is set while
+  # acts_as_tenant is not loaded.
+<% if tenant_model %>  config.tenant_model = '<%= tenant_model %>'
+<% else %>  # config.tenant_model = 'Account'
+<% end %>
+  # The admin screens and the admin API serve one tenant at a time: a request
+  # with no current tenant is refused (403). Set the tenant in
+  # base_controller_class / api_base_controller_class (or in middleware).
+  # config.admin_tenantless_access = :deny
+
+  # ---------------------------------------------------------------------------
+  # Activation conditions (session flag / allowed IPs / login hours)
+  # ---------------------------------------------------------------------------
+  # With conditional_sets_strict_mode (set above), where the request context is
+  # blank (no resolver, a job, the console) a conditional GRANTING set does not
+  # apply and a conditional MUTING set (a lockdown) does. Trade-off: an MFA- or
+  # IP-gated grant never applies in jobs or the console, nor in requests until
+  # this resolver returns the request's IP and session flags:
+  # config.request_context_resolver = -> {
+  #   { ip: Current.ip, session_flags: Current.session_flags, time: Time.current }
+  # }
+  # It runs on every permission read of a user who holds a conditional set:
+  # keep it cheap, never read permissions inside it, return {} with no request.
+
+  # ---------------------------------------------------------------------------
+  # Masked attributes with nobody signed in (not part of the preset)
+  # ---------------------------------------------------------------------------
+  # :bypass (default) returns the stored values; :hide hides every guarded
+  # attribute. Trade-off: jobs, mailers and console code that read masked
+  # models with no user then see hidden values: set the current user there.
+  # The user model (user_class and its subclasses) stays readable for sign-in,
+  # and validations always read the stored values.
+  # config.masked_attributes_nil_user_strategy = :hide
+
+  # ---------------------------------------------------------------------------
+  # Admin screens
+  # ---------------------------------------------------------------------------
+  # HTTP Basic auth is on and answers 401 until credentials are set. Never turn
+  # it off without the second option: the admin can grant anything to anyone.
+  #
+  # Option A — Basic auth credentials (from ENV or credentials, never literals):
+  # config.http_basic_auth_user     = ENV['PF_ADMIN_USER']
+  # config.http_basic_auth_password = ENV['PF_ADMIN_PASSWORD']
+  #
+  # Option B — your own authenticated admin controller:
+  # config.http_basic_auth_enabled = false
+  # config.base_controller_class   = '::Admin::BaseController'  # must authenticate admins
+  #
+  # Who may grant, revoke, extend or review an assignment, or change a group's
+  # members (admin screens and API). Example: no self-assignment.
+  # config.admin_assignment_authorization = ->(controller, target, user_ids, action) {
+  #   admin = controller.current_user
+  #   admin&.admin? && !user_ids.include?(admin.id)
+  # }
+  #
+  # Who may read the audit log pages, exports and API (nil: anyone with admin access).
+  # config.audit_log_authorization = ->(controller) { controller.current_user&.auditor? }
+
+  # ---------------------------------------------------------------------------
+  # Audit log (docs/audit-log.md)
+  # ---------------------------------------------------------------------------
+  # Every permission change is recorded in the audit_events table, inside the
+  # change's own transaction. Each option with its default (an example where that is nil):
+  # config.audit_events = :auto                    # true: always; false: never (events are still published)
+  # config.audit_actor_resolver = ->(controller) { controller.current_user }  # nil: current_user_resolver
+  # config.audit_request_context = ->(controller) { { request_id: controller.request.request_id, ip: controller.request.remote_ip } }
+  # config.audit_change_failure_strategy = :raise  # the change rolls back; or :report, :log
+  # config.audit_hook_failure_strategy = :report   # or :log, :raise
+  # config.audit_runtime_events = %i[denied]       # also: bypass field_read params_filtered cache
+  # config.audit_log_subscriber = false            # true: also write every event to Rails.logger
+  # config.audit_retention_period = 2.years        # nil keeps events forever; purge: bin/rails permission_forge:audit_events:purge
+  # In jobs and rake tasks: PermissionForge.with_audit_actor(user: admin, source: 'job') { ... }
+
+  # ---------------------------------------------------------------------------
+  # JSON admin API (off by default)
+  # ---------------------------------------------------------------------------
+  # config.api_enabled = true
+  # config.api_base_controller_class = '::Api::BaseController'  # your auth chain
+  # config.api_auth = ->(controller) { controller.current_user&.admin? }
+  # config.api_action_authorization = ->(controller, action, record) { controller.current_user&.admin? }
+  # config.api_assignment_authorization = ->(controller, permission_set, user_ids) { controller.current_user&.admin? }
+  #
+  # api_auth proves identity only: until both authorization lambdas are set,
+  # every API change and assignment is refused (403).
+  # config.api_require_authorization = true  # default
+end

data/lib/generators/permission_forge/install/templates/migration.rb.tt

@@ -0,0 +1,198 @@
+class CreatePermissionForgeTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :<%= table_prefix %>permission_set_groups do |t|
+      t.string  :uuid, null: false
+      t.string  :name, null: false, default: 'Untitled Permission Set Group'
+      t.string  :description
+      t.boolean :is_active, null: false, default: true
+      t.boolean :is_editable, null: false, default: true
+<% if tenant_column %>      t.<%= tenant_id_type %>  :<%= tenant_column %>
+      t.index   :<%= tenant_column %>
+<% end %>      t.<%= user_id_type %>  :created_by_id
+      t.<%= user_id_type %>  :updated_by_id
+      t.timestamps
+
+      t.index :uuid, unique: true
+    end
+
+    create_table :<%= table_prefix %>permission_sets do |t|
+      t.string     :uuid, null: false
+      t.references :permission_set_group, foreign_key: { to_table: :<%= table_prefix %>permission_set_groups }, null: true
+      t.string     :name, null: false, default: 'Untitled Permission Set'
+      t.string     :description
+      t.boolean    :is_active, null: false, default: true
+      t.boolean    :is_editable, null: false, default: true
+      t.boolean    :is_muting, null: false, default: false
+      t.string     :requires_session_flag
+      t.string     :allowed_ips
+      t.integer    :allowed_hours_start
+      t.integer    :allowed_hours_end
+<% if tenant_column %>      t.<%= tenant_id_type %>     :<%= tenant_column %>
+      t.index      :<%= tenant_column %>
+<% end %>      t.<%= user_id_type %>     :created_by_id
+      t.<%= user_id_type %>     :updated_by_id
+      t.timestamps
+
+      t.index :uuid, unique: true
+    end
+
+    create_table :<%= table_prefix %>resources do |t|
+      t.string     :uuid, null: false
+      t.references :permission_set, foreign_key: { to_table: :<%= table_prefix %>permission_sets }, null: false
+      t.string     :name, null: false, default: 'Untitled Resource'
+      t.string     :label
+      t.string     :description
+      t.boolean    :is_active, null: false, default: true
+      t.boolean    :is_editable, null: false, default: true
+      t.boolean    :read_access, null: false, default: false
+      t.boolean    :create_access, null: false, default: false
+      t.boolean    :edit_access, null: false, default: false
+      t.boolean    :delete_access, null: false, default: false
+      t.boolean    :view_all, null: false, default: false
+      t.boolean    :modify_all, null: false, default: false
+<% if tenant_column %>      t.<%= tenant_id_type %>     :<%= tenant_column %>
+      t.index      :<%= tenant_column %>
+<% end %>      t.<%= user_id_type %>     :created_by_id
+      t.<%= user_id_type %>     :updated_by_id
+      t.timestamps
+
+      t.index :uuid, unique: true
+      t.index [:permission_set_id, :name], unique: true, name: 'idx_pf_resources_unique'
+    end
+
+    create_table :<%= table_prefix %>resource_fields do |t|
+      t.string     :uuid, null: false
+      t.references :resource, foreign_key: { to_table: :<%= table_prefix %>resources }, null: false
+      t.string     :name, null: false, default: 'untitled_field'
+      t.string     :label, null: false, default: 'Untitled Field'
+      t.string     :description
+      t.boolean    :is_active, null: false, default: true
+      t.boolean    :is_editable, null: false, default: true
+      t.boolean    :read_access, null: false, default: false
+      t.boolean    :edit_access, null: false, default: false
+      t.boolean    :mask_access, null: false, default: false
+      t.string     :mask_strategy, null: false, default: 'full'
+      t.datetime   :sensitive_acknowledged_at
+      t.<%= user_id_type %>     :sensitive_acknowledged_by_id
+<% if tenant_column %>      t.<%= tenant_id_type %>     :<%= tenant_column %>
+      t.index      :<%= tenant_column %>
+<% end %>      t.<%= user_id_type %>     :created_by_id
+      t.<%= user_id_type %>     :updated_by_id
+      t.timestamps
+
+      t.index :uuid, unique: true
+      t.index [:resource_id, :name], unique: true, name: 'idx_pf_resource_fields_unique'
+    end
+
+    create_table :<%= table_prefix %>resource_actions do |t|
+      t.string     :uuid, null: false
+      t.references :resource, foreign_key: { to_table: :<%= table_prefix %>resources }, null: false
+      t.string     :name, null: false
+      t.string     :label
+      t.string     :description
+      t.boolean    :is_permitted, null: false, default: false
+      t.boolean    :is_active, null: false, default: true
+<% if tenant_column %>      t.<%= tenant_id_type %>     :<%= tenant_column %>
+      t.index      :<%= tenant_column %>
+<% end %>      t.<%= user_id_type %>     :created_by_id
+      t.<%= user_id_type %>     :updated_by_id
+      t.timestamps
+
+      t.index :uuid, unique: true
+      t.index [:resource_id, :name], unique: true, name: 'idx_pf_resource_actions_unique'
+    end
+
+    create_table :<%= table_prefix %>permission_set_rules do |t|
+      t.string     :uuid, null: false
+      t.references :permission_set, foreign_key: { to_table: :<%= table_prefix %>permission_sets }, null: false
+      t.references :resource, foreign_key: { to_table: :<%= table_prefix %>resources }, null: false
+      t.string     :name, null: false, default: 'Untitled Rule'
+      t.string     :failure_message, default: 'You do not have permission to perform this action.'
+      t.string     :join_type
+      t.string     :field_name, null: false
+      t.string     :field_value, null: false
+      t.string     :field_accessor_path
+      t.string     :operator, null: false, default: 'equal'
+      t.boolean    :include_nulls, null: false, default: true
+      t.boolean    :is_active, null: false, default: true
+      t.boolean    :is_editable, null: false, default: true
+<% if tenant_column %>      t.<%= tenant_id_type %>     :<%= tenant_column %>
+      t.index      :<%= tenant_column %>
+<% end %>      t.<%= user_id_type %>     :created_by_id
+      t.<%= user_id_type %>     :updated_by_id
+      t.timestamps
+
+      t.index :uuid, unique: true
+    end
+
+    create_table :<%= table_prefix %>permission_set_users do |t|
+      t.string     :uuid, null: false
+      t.references :permission_set, foreign_key: { to_table: :<%= table_prefix %>permission_sets }, null: false
+      t.references :user, null: false, type: :<%= user_id_type %>
+      t.datetime   :expires_at
+      t.datetime   :reviewed_at
+      t.<%= user_id_type %>     :reviewed_by_id
+      t.string     :reason
+<% if tenant_column %>      t.<%= tenant_id_type %>     :<%= tenant_column %>
+      t.index      :<%= tenant_column %>
+<% end %>      t.<%= user_id_type %>     :created_by_id
+      t.<%= user_id_type %>     :updated_by_id
+      t.timestamps
+
+      t.index :uuid, unique: true
+      t.index [:permission_set_id, :user_id], unique: true, name: 'idx_pf_pset_users_unique'
+    end
+
+    create_table :<%= table_prefix %>permission_set_group_users do |t|
+      t.string     :uuid, null: false
+      t.references :permission_set_group, foreign_key: { to_table: :<%= table_prefix %>permission_set_groups }, null: false
+      t.references :user, null: false, type: :<%= user_id_type %>
+      t.string     :reason
+<% if tenant_column %>      t.<%= tenant_id_type %>     :<%= tenant_column %>
+      t.index      :<%= tenant_column %>
+<% end %>      t.<%= user_id_type %>     :created_by_id
+      t.<%= user_id_type %>     :updated_by_id
+      t.timestamps
+
+      t.index :uuid, unique: true
+      t.index [:permission_set_group_id, :user_id], unique: true, name: 'idx_pf_pset_group_users_unique'
+    end
+
+    # Insert-only audit log. No foreign keys: events outlive the records they describe.
+    create_table :<%= table_prefix %>audit_events do |t|
+      t.string   :uuid, null: false
+      t.datetime :occurred_at, null: false, precision: 6
+      t.string   :event, null: false
+      t.string   :category, null: false
+      t.string   :actor_type, null: false
+      t.string   :actor_id
+      t.string   :actor_label
+      t.string   :source, null: false
+      t.string   :record_type
+      t.string   :record_id
+      t.string   :record_uuid
+      t.string   :record_label
+      t.bigint   :permission_set_id
+      t.string   :permission_set_uuid
+      t.string   :subject_user_id
+      t.text     :data
+      t.string   :reason
+      t.string   :request_id
+      t.string   :ip
+      t.string   :correlation_id
+<% if tenant_column %>      t.<%= tenant_id_type %>   :<%= tenant_column %>
+      t.index    :<%= tenant_column %>, name: 'idx_pf_audit_tenant'
+<% end %>      t.datetime :created_at, null: false
+
+      t.index :uuid, unique: true, name: 'idx_pf_audit_uuid'
+      t.index :occurred_at, name: 'idx_pf_audit_occurred'
+      t.index [:event, :occurred_at], name: 'idx_pf_audit_event'
+      t.index [:subject_user_id, :occurred_at], name: 'idx_pf_audit_subject'
+      t.index [:permission_set_id, :occurred_at], name: 'idx_pf_audit_pset'
+      t.index [:permission_set_uuid, :occurred_at], name: 'idx_pf_audit_pset_uuid'
+      t.index [:record_type, :record_id, :occurred_at], name: 'idx_pf_audit_record'
+      t.index [:actor_id, :occurred_at], name: 'idx_pf_audit_actor'
+      t.index :correlation_id, name: 'idx_pf_audit_correlation'
+    end
+  end
+end

data/lib/generators/permission_forge/rls/rls_generator.rb

@@ -0,0 +1,57 @@
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module PermissionForge
+  # @api private
+  module Generators
+    # Installs Postgres Row-Level Security for PermissionForge (Level 3).
+    #
+    #   bin/rails generate permission_forge:rls
+    #
+    # Creates a migration that enables (and forces) RLS on every protected
+    # table and installs policies generated from the current rule state via
+    # PermissionForge::RLS.sync!. After editing rules, re-sync with
+    # `rake permission_forge:rls:sync` (drift is warned about at boot).
+    #
+    # Requires PostgreSQL and config.database_row_level_security = true for the
+    # runtime session-variable plumbing.
+    class RlsGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      def check_adapter
+        return if PermissionForge::RLS.postgres?
+
+        say_status :error, 'PermissionForge RLS requires PostgreSQL — aborting.', :red
+        raise Thor::Error, 'database adapter is not PostgreSQL'
+      end
+
+      def copy_migration
+        migration_template 'enable_permission_forge_rls.rb.tt',
+                           'db/migrate/enable_permission_forge_rls.rb'
+      end
+
+      def show_post_install
+        say <<~MSG
+
+          RLS migration created. Next steps:
+            1. bin/rails db:migrate
+            2. Set config.database_row_level_security = true in the initializer
+            3. Wrap request/job execution: PermissionForge::RLS.with_user(user) { ... }
+               (or set_user!/clear_user! in an around_action)
+            4. After editing permission rules: rake permission_forge:rls:sync
+
+          IMPORTANT: connect as a NON-superuser role without BYPASSRLS —
+          superusers bypass row-level security entirely.
+        MSG
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::Migration.current_version}]"
+      end
+    end
+  end
+end

data/lib/generators/permission_forge/rls/templates/enable_permission_forge_rls.rb.tt

@@ -0,0 +1,15 @@
+# Enables Postgres Row-Level Security on all PermissionForge-protected tables
+# and installs policies generated from the current rule state.
+#
+# Policies check set membership dynamically (assign/revoke needs NO resync) but
+# bake rule content statically — after editing permission rules, run:
+#   rake permission_forge:rls:sync
+class EnablePermissionForgeRls < ActiveRecord::Migration<%= migration_version %>
+  def up
+    PermissionForge::RLS.sync!
+  end
+
+  def down
+    PermissionForge::RLS.remove!
+  end
+end

data/lib/generators/permission_forge/upgrade/templates/add_admin_ui_columns.rb.tt

@@ -0,0 +1,8 @@
+class PermissionForgeAddAdminUiColumns < ActiveRecord::Migration<%= migration_version %>
+  # Nullable and additive: safe to run on a live table. The admin UI checks for
+  # the column and simply hides "This is intended" until it exists.
+  def change
+    add_column :<%= table_prefix %>resource_fields, :sensitive_acknowledged_at, :datetime,
+               if_not_exists: true
+  end
+end