permission_forge 0.14.1

data/lib/permission_forge/services/concerns/audited_operation.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Services
+    module Concerns
+      # Runs a housekeeping service under an audit context: who ran it (`actor:`),
+      # why (`reason:`), from where, and one correlation id for the per-row events
+      # and the summary event it writes.
+      #
+      # `actor:` is a host user, an Audit::Actor, or a label String (stored as a
+      # 'system' actor). nil names nobody: the context already in force (a request's
+      # admin, a rake task's ACTOR, PermissionForge.current_user) stays — an explicit
+      # nil never replaces a real actor.
+      #
+      # The source is 'service' unless the caller's context, or the process (rake,
+      # console), already says where the call came from.
+      module AuditedOperation
+        private
+
+        def audited(actor:, reason:, &)
+          PermissionForge::Audit::Context.with(actor: audit_actor_for(actor), source: audit_source, reason: reason) do
+            PermissionForge::Audit.correlate(&)
+          end
+        end
+
+        # @return [PermissionForge::Audit::Actor, nil]
+        def audit_actor_for(actor)
+          case actor
+          when nil then nil
+          when String then PermissionForge::Audit::Actor.system(actor)
+          else PermissionForge::Audit::Actor.coerce(actor)
+          end
+        end
+
+        def audit_source
+          return if PermissionForge::Audit::Context[:source]
+
+          'service' if PermissionForge::Audit::Source.detect == 'service'
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/services/concerns/clonable.rb

@@ -0,0 +1,29 @@
+module PermissionForge
+  module Services
+    # Copies one record as a new row. The copy is a new record in every sense:
+    # its own uuid, and no author or editor carried over from the original —
+    # HasAuditTrail credits whoever makes the copy, and the copy's create
+    # event (RecordsAuditEvents) names the same person. A field's "This is
+    # intended" acknowledgement is one person's attestation about one set, so
+    # a copy starts unacknowledged.
+    #
+    # @api private
+    module Clonable
+      # Columns a copy never takes from its original (those the table has).
+      RESET_ON_COPY = %w[uuid created_by_id updated_by_id sensitive_acknowledged_at sensitive_acknowledged_by_id].freeze
+
+      private
+
+      def duplicate_record(record, **attrs)
+        cloned = record.dup
+        cloned.assign_attributes(reset_on_copy(cloned).merge(attrs))
+        cloned.save!
+        cloned
+      end
+
+      def reset_on_copy(record)
+        RESET_ON_COPY.select { |column| record.has_attribute?(column) }.index_with(nil)
+      end
+    end
+  end
+end

data/lib/permission_forge/services/consent_withdrawal_handler.rb

@@ -0,0 +1,135 @@
+module PermissionForge
+  module Services
+    # Handles consent withdrawal by removing a user from all permission sets
+    # gated on the specified consent flag, then invalidating the user's cached
+    # permissions (rebuilt read-through on next access).
+    #
+    # @example Withdraw marketing consent
+    #   result = ConsentWithdrawalHandler.call(
+    #     user: user,
+    #     consent_flag: 'marketing_consent'
+    #   )
+    #   # => { revoked_sets: 2, invalidated: true }
+    #
+    # `invalidated` is false when nothing was revoked, and when the cache
+    # store did not confirm the invalidation (reported through
+    # `config.on_cache_failure`).
+    #
+    # @example Dry run (inspect without revoking)
+    #   result = ConsentWithdrawalHandler.call(
+    #     user: user,
+    #     consent_flag: 'marketing_consent',
+    #     dry_run: true
+    #   )
+    #   # => { revoked_sets: 0, affected_sets: ["Marketing Access"], dry_run: true }
+    #
+    # The audit log: assignments are destroyed through their callbacks (one
+    # `assignment.revoked` each), then ONE `consent.withdrawn` event names the
+    # person, the flag, the sets and the counts. `actor:` (a user, an
+    # Audit::Actor or a label String) and `reason:` say who ran it and why.
+    # A dry run writes nothing.
+    #
+    # The revocations and `consent.withdrawn` happen in ONE transaction, like
+    # DataSubjectErasure: if the summary cannot be written under
+    # audit_change_failure_strategy :raise, no assignment is removed. The
+    # cache invalidation runs after the commit (so the summary does not say
+    # whether the store confirmed it; the result's `invalidated` does).
+    #
+    # Tenants: with a tenant ambient, the person's assignments in that
+    # tenant. With none (a platform task) in every tenant — also under
+    # acts_as_tenant's require_tenant — and `consent.withdrawn` is written in
+    # each tenant that lost assignments (its sets and count) plus once
+    # without a tenant (the totals), each with `across_tenants: true`
+    # (Concerns::AcrossTenants).
+    #
+    # @api public
+    class ConsentWithdrawalHandler
+      include Concerns::AuditedOperation
+      include Concerns::AcrossTenants
+
+      # Removes a user from every Permission Set gated on the consent flag.
+      # @return [Hash] see {#call}
+      def self.call(...) = new(...).call
+
+      def initialize(user:, consent_flag:, dry_run: false, actor: nil, reason: nil)
+        @user = user
+        @consent_flag = consent_flag
+        @dry_run = dry_run
+        @actor = actor
+        @reason = reason
+      end
+
+      # @return [Hash] `{ revoked_sets:, invalidated: }` (plus `affected_sets:` and `dry_run:` for a dry run)
+      def call
+        validate!
+
+        across_tenants do
+          affected_sets = consent_gated_sets
+          affected_assignments = user_assignments_for(affected_sets)
+          next dry_run_result(affected_sets, affected_assignments) if @dry_run
+
+          audited(actor: @actor, reason: @reason) { withdraw(affected_assignments) }
+        end
+      end
+
+      private
+
+      def withdraw(affected_assignments)
+        revoked_count = ActiveRecord::Base.transaction { revoke_and_record(affected_assignments) }
+        # what the store confirmed — not what a host's override of the method returns
+        invalidated = revoked_count.positive? && PermissionForge::Cache::Failure.none? { @user.invalidate_permissions }
+
+        { revoked_sets: revoked_count, invalidated: invalidated }
+      end
+
+      def revoke_and_record(affected_assignments)
+        assignments = affected_assignments.includes(:permission_set).to_a
+        revoked = assignments.select { |assignment| assignment.destroy.present? }
+        record_summary(assignments, revoked)
+        revoked.size
+      end
+
+      # One event, or one per tenant plus the totals (record_per_tenant).
+      # Each names the sets of its assignments and counts the revoked ones.
+      def record_summary(assignments, revoked)
+        record_per_tenant('consent.withdrawn', assignments, subject_user_id: @user.id) do |rows|
+          summary_data(rows.filter_map(&:permission_set), rows.count { |row| revoked.include?(row) })
+        end
+      end
+
+      def summary_data(sets, revoked_count)
+        {
+          'operation' => 'consent_withdrawal',
+          'consent_flag' => @consent_flag.to_s,
+          'subject_user_id' => @user.id.to_s,
+          'set_uuids' => sets.map(&:uuid).uniq,
+          'set_names' => sets.map(&:name).uniq,
+          'revoked' => revoked_count,
+          'dry_run' => false
+        }
+      end
+
+      def validate!
+        raise ArgumentError, 'user is required' if @user.nil?
+        raise ArgumentError, 'consent_flag is required' if @consent_flag.blank?
+      end
+
+      def consent_gated_sets
+        PermissionForge::PermissionSet.where(requires_session_flag: @consent_flag)
+      end
+
+      def user_assignments_for(sets)
+        PermissionForge::PermissionSetUser.where(user: @user, permission_set: sets)
+      end
+
+      def dry_run_result(sets, assignments)
+        {
+          revoked_sets: 0,
+          affected_sets: sets.pluck(:name),
+          affected_assignment_count: assignments.count,
+          dry_run: true
+        }
+      end
+    end
+  end
+end

data/lib/permission_forge/services/dashboard_stats.rb

@@ -0,0 +1,43 @@
+module PermissionForge
+  module Services
+    # Aggregates dashboard statistics from permission models.
+    # Extracted from DashboardController for SRP.
+    #
+    # @api private
+    class DashboardStats
+      def self.call
+        {}.merge(permission_set_stats).merge(model_counts).merge(recent_records)
+      end
+
+      class << self
+        private
+
+        def permission_set_stats
+          {
+            permission_sets_count: PermissionForge::PermissionSet.count,
+            active_sets_count: PermissionForge::PermissionSet.active.count,
+            muting_sets_count: PermissionForge::PermissionSet.muting.count,
+            conditional_sets_count: PermissionForge::PermissionSet.conditional.count,
+            expired_assignments_count: PermissionForge::PermissionSetUser.expired.count
+          }
+        end
+
+        def model_counts
+          {
+            resources_count: PermissionForge::Resource.count,
+            rules_count: PermissionForge::PermissionSetRule.count,
+            groups_count: PermissionForge::PermissionSetGroup.count,
+            users_count: PermissionForge::PermissionSetUser.select(:user_id).distinct.count
+          }
+        end
+
+        def recent_records
+          {
+            recent_permission_sets: PermissionForge::PermissionSet.order(created_at: :desc).limit(5),
+            recent_resources: PermissionForge::Resource.order(created_at: :desc).limit(5)
+          }
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/services/data_subject_erasure.rb

@@ -0,0 +1,306 @@
+module PermissionForge
+  module Services
+    # Supports a GDPR Art. 17 (right to erasure) request for a host user.
+    # What it removes:
+    #   - the person's permission set assignments and group memberships, in
+    #     the ambient tenant, each through its callbacks (one audit event per
+    #     row);
+    #   - the person's cached permissions;
+    #   - the person's name labels in the audit log (actor_label on events
+    #     they acted in, record_label on events about them): with a tenant
+    #     current, in that tenant's events; with none (the rake task, a
+    #     platform operator), in every tenant's, events without a tenant
+    #     included;
+    #   - whatever the host's `on_erasure` callback deletes.
+    # What remains, so the log still says what happened:
+    #   - every audit event keeps its ids (actor_id, subject_user_id), ip,
+    #     request_id, reason and data (snapshots of the removed rows);
+    #   - created_by_id / updated_by_id / reviewed_by_id /
+    #     sensitive_acknowledged_by_id on rows the person created, edited or
+    #     reviewed;
+    #   - assignments and memberships in other tenants when a tenant is
+    #     current (counted in `assignments_remaining_elsewhere` and
+    #     `group_assignments_remaining_elsewhere`);
+    #   - the person's own record and data in the host app, unless
+    #     `on_erasure` deletes them.
+    #
+    # @example Full erasure
+    #   result = DataSubjectErasure.call(user: user)
+    #   # => { assignments_removed: 3, group_assignments_removed: 1, cache_cleared: true, callback_invoked: true }
+    #
+    # `cache_cleared` is false when the cache store did not confirm the
+    # removal (it is unreachable, say): the assignments are gone, but the
+    # user's cached permissions may live until cache_ttl. The failure is also
+    # reported through `config.on_cache_failure`. It is nil when the service
+    # is called inside a database transaction: the assignments are only gone
+    # for everybody else — and their cached permissions with them — once that
+    # transaction has committed, and a failure then is reported through
+    # `config.on_cache_failure` alone.
+    #
+    # @example Dry run (inspect without removing)
+    #   result = DataSubjectErasure.call(user: user, dry_run: true)
+    #   # => { assignments_count: 3, group_assignments_count: 1, permission_sets: [...], dry_run: true }
+    #
+    # The audit log (docs/audit-log.md): the rows are destroyed through their
+    # callbacks, so each assignment writes its own `assignment.revoked`
+    # event; then the personal labels the log holds about the person are
+    # cleared and ONE `erasure.performed` event is written. `actor:` (a user,
+    # an Audit::Actor or a label String; nil means the actor of the context)
+    # and `reason:` say who ran it and why. A dry run writes nothing at all.
+    #
+    # The row removal, the label scrub and `erasure.performed` happen in ONE
+    # transaction: if the summary cannot be written under
+    # audit_change_failure_strategy :raise, nothing changed. Under :report or
+    # :log the host chose that changes go through when their record fails: the
+    # erasure completes without `erasure.performed` (the failure is reported) —
+    # the right to erasure is not blocked by the audit write. The cache
+    # invalidation and `on_erasure` run after it. Events a callback writes
+    # afterwards keep the labels they were given, so a host callback must not
+    # create assignments for the erased person.
+    #
+    # `on_erasure` runs once the erasure is committed for everybody:
+    #   - called outside a transaction, right after the erasure; if it
+    #     raises, the erasure stands and is recorded, and the error propagates
+    #     (`callback_invoked` is true);
+    #   - called inside the caller's transaction, after that transaction has
+    #     committed (OpenTransaction#after_commit), and never if it rolls
+    #     back (`callback_invoked` is nil: only known at the commit). An
+    #     error there is logged and reported (Rails.error, `handled: true`,
+    #     like every after-commit error the gem catches), not raised: raising
+    #     from Rails' commit would skip the after-commit work queued behind
+    #     it, the cache invalidations of the caller's other changes included.
+    #
+    # With no tenant ambient the service runs over every tenant also under
+    # acts_as_tenant's require_tenant (Concerns::AcrossTenants).
+    #
+    # @api public
+    class DataSubjectErasure
+      include Concerns::AuditedOperation
+      include Concerns::AcrossTenants
+
+      # Erases a user's permission data (GDPR Art. 17).
+      # @return [Hash] see {#call}
+      def self.call(...) = new(...).call
+
+      def initialize(user:, on_erasure: nil, dry_run: false, actor: nil, reason: nil)
+        @user = user
+        @on_erasure = on_erasure
+        @dry_run = dry_run
+        @actor = actor
+        @reason = reason
+      end
+
+      # @return [Hash] the counts of what was removed and what remains
+      def call
+        validate!
+
+        across_tenants do
+          next dry_run_result if @dry_run
+
+          audited(actor: erased_person_unnamed, reason: @reason) { erase }
+        end
+      end
+
+      private
+
+      def erase
+        removed = ActiveRecord::Base.transaction { remove_and_record }
+        cache_cleared = clear_cache
+
+        removed.merge(cache_cleared: cache_cleared, callback_invoked: run_callback)
+      end
+
+      def remove_and_record
+        sets = permission_set_assignments.includes(:permission_set).filter_map(&:permission_set)
+        groups = group_assignments.includes(:permission_set_group).filter_map(&:permission_set_group)
+
+        counts = { assignments_removed: remove_permission_set_assignments,
+                   group_assignments_removed: remove_group_assignments }
+        counts.merge!(remaining_elsewhere)
+        scrubbed = scrub_labels
+        record_summary(sets, groups, counts, scrubbed)
+        counts
+      end
+
+      # What the person still has in other tenants (nothing is removed there).
+      def remaining_elsewhere
+        {
+          assignments_remaining_elsewhere: PermissionForge::PermissionSetUser.unscoped.where(user: @user).count,
+          group_assignments_remaining_elsewhere: PermissionForge::PermissionSetGroupUser.unscoped.where(user: @user).count
+        }
+      end
+
+      # A person who erases themselves must not leave their own name on the
+      # events of the erasure: the id stays, the label does not. Without
+      # `actor:` the context's actor (the admin of the request) is the one
+      # compared.
+      def erased_person_unnamed
+        resolved = audit_actor_for(@actor) || PermissionForge::Audit::Actor.current
+        return @actor unless resolved.type == 'user' && resolved.id == @user.id.to_s
+
+        PermissionForge::Audit::Actor.new(type: resolved.type, id: resolved.id)
+      end
+
+      # The only sanctioned mutation of audit events: the snapshots of the
+      # person's name. Every id stays, so the trail still says WHAT happened;
+      # only WHO (as a name) is forgotten. Past the insert-only guards on
+      # purpose (`update_all` is the one path T1 leaves open), in the events
+      # of scrubbed_events, only for actors of type 'user' (an API key or a
+      # basic auth login that shares the id is somebody else), and recorded
+      # in `erasure.performed`.
+      def scrub_labels
+        events = scrubbed_events
+        id = @user.id.to_s
+        {
+          actor_labels: events.where(actor_type: 'user', actor_id: id).where.not(actor_label: nil).update_all(actor_label: nil),
+          record_labels: events.where(subject_user_id: id).where.not(record_label: nil).update_all(record_label: nil)
+        }
+      end
+
+      # With a tenant current (a tenant admin), that tenant's events only: a
+      # tenant cannot reach another tenant's log. With none (the rake task, a
+      # platform operator), every tenant's, and the events without a tenant.
+      # Built on `unscoped` and an explicit tenant condition, so it does not
+      # depend on acts_as_tenant's default scope. An events table without the
+      # tenant column cannot be told apart by tenant: every event.
+      def scrubbed_events
+        PermissionForge::AuditEvent.unscoped.in_tenant(PermissionForge.ambient_tenant_id)
+      end
+
+      def record_summary(sets, groups, counts, scrubbed)
+        PermissionForge::Audit.record('erasure.performed', subject_user_id: @user.id,
+                                                           data: summary_data(sets, groups, counts, scrubbed))
+      end
+
+      def summary_data(sets, groups, counts, scrubbed)
+        cleared = { 'events_scrubbed' => scrubbed.values.sum, 'actor_labels_cleared' => scrubbed[:actor_labels],
+                    'record_labels_cleared' => scrubbed[:record_labels] }
+        names(sets, 'set').merge(names(groups, 'group'), counts.transform_keys(&:to_s), cleared,
+                                 'operation' => 'erasure', 'subject_user_id' => @user.id.to_s,
+                                 'callback_invoked' => !@on_erasure.nil?, 'dry_run' => false)
+      end
+
+      def names(records, kind)
+        { "#{kind}_uuids" => records.map(&:uuid).uniq, "#{kind}_names" => records.map(&:name).uniq }
+      end
+
+      def validate!
+        raise ArgumentError, 'user is required' if @user.nil?
+      end
+
+      def permission_set_assignments
+        PermissionForge::PermissionSetUser.where(user: @user)
+      end
+
+      def group_assignments
+        PermissionForge::PermissionSetGroupUser.where(user: @user)
+      end
+
+      def remove_permission_set_assignments
+        records = permission_set_assignments
+        count = records.count
+        records.destroy_all
+        count
+      end
+
+      def remove_group_assignments
+        records = group_assignments
+        count = records.count
+        records.destroy_all
+        count
+      end
+
+      # Asks the gem's own failure bookkeeping, not the value of
+      # invalidate_permissions: a host app overrides that method.
+      #
+      # An invalidation leaves the per-context variants of a user with
+      # conditional sets to their TTL (unreachable). They hold the profile,
+      # so they are removed as well (Cache::VariantRemoval) — inside the
+      # caller's transaction once it has committed, after the assignments'
+      # own invalidations: until then another request may still cache one
+      # from the rows as they were.
+      #
+      # @return [Boolean, nil] whether the store confirmed the removal; nil
+      #   inside an open transaction, where that is only known at its commit
+      def clear_cache
+        transaction = PermissionForge::OpenTransaction.current
+        cleared = PermissionForge::Cache::Failure.none? do
+          invalidate_user
+          PermissionForge::Cache::VariantRemoval.call(**variant_removal) unless transaction
+        end
+        return cleared unless transaction
+
+        remove_variants_after_commit(transaction)
+        nil
+      end
+
+      # The arguments of the person's Cache::VariantRemoval: the keys the
+      # instance names, as invalidate_permissions removes them, every slot of
+      # each without reading the index entries (a read that fails silently
+      # and an evicted index entry must not leave a variant behind).
+      def variant_removal
+        named = @user.respond_to?(:permission_cache_key) ? { ambient_key: @user.permission_cache_key } : {}
+        { user_ids: [@user.id], indexed_only: false, **named }
+      end
+
+      # Nothing raises out of the commit: a failure is reported, like every
+      # after-commit invalidation (Cache::Failure).
+      def remove_variants_after_commit(transaction)
+        removal = variant_removal
+        transaction.after_commit do
+          PermissionForge::Cache::VariantRemoval.call(**removal)
+        rescue StandardError => e
+          PermissionForge::Cache::Failure.report(operation: :invalidate, user_id: removal[:user_ids].first, error: e)
+        end
+      end
+
+      def invalidate_user
+        # invalidate_permissions (not a raw cache delete) so the ambient and
+        # tenant-agnostic keys are both removed AND the process-wide memo
+        # version bumps — no live instance may keep serving an erased user's
+        # permissions from its instance memo.
+        return @user.invalidate_permissions if @user.respond_to?(:invalidate_permissions)
+
+        cache = PermissionForge.cache
+        key = @user.permission_cache_key
+        PermissionForge::Cache::Failure.report(operation: :invalidate, keys: [key]) unless cache.expunge(key)
+        PermissionForge.bump_permissions_cache_version!
+      end
+
+      # @return [Boolean, nil] false without a callback; true once it ran;
+      #   nil when it waits for the caller's transaction to commit
+      def run_callback
+        return false if @on_erasure.nil?
+
+        transaction = PermissionForge::OpenTransaction.current
+        return defer_callback(transaction) if transaction
+
+        @on_erasure.call(@user)
+        true
+      end
+
+      def defer_callback(transaction)
+        callback = @on_erasure
+        user = @user
+        transaction.after_commit { report_callback_failure { callback.call(user) } }
+        nil
+      end
+
+      def report_callback_failure
+        yield
+      rescue StandardError => e
+        Rails.logger&.error("[PermissionForge] on_erasure failed after the erasure committed — #{e.class}: #{e.message}")
+        Rails.error.report(e, handled: true, source: 'permission_forge.data_subject_erasure')
+      end
+
+      def dry_run_result
+        {
+          assignments_count: permission_set_assignments.count,
+          group_assignments_count: group_assignments.count,
+          permission_sets: permission_set_assignments.includes(:permission_set).filter_map { |psu| psu.permission_set&.name },
+          dry_run: true
+        }
+      end
+    end
+  end
+end