ask-permissions 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af1fd0c9368ebb102f0ca805b7303d781bf29e862ea19145fc4efcf24025cbe9
-  data.tar.gz: 4ce78f5aaf769b55fde844e1de746c319bcbc33001e7e9cb1f90a25e1c9a4850
+  metadata.gz: c087f59df91e1c192c30e0e6740ad8fe8d514da85d2e1c14fe29f21df1bfeb0b
+  data.tar.gz: 6463c8e2123aa2b2035905a9fd8ef1df602f3ad9bdbe7f04afb6d8dd8e7acb63
 SHA512:
-  metadata.gz: ab3cd320947d7426dfececa4f73625df5d073fc751249521ac93e4104eaaa36d43512d30f6b9c92e25be60c9eafc26b7327f0bc9593ca2f80d614c7cba5efc44
-  data.tar.gz: 29e4857b244341160b6fd856c056c5fc3f098bbf350b9f07424c8ab8b3c90de3bac55c505c5b0e2d461d2a5efa22a73e9bc3c943a989807bb747771b3d8e1982
+  metadata.gz: e4c4934516b4f0bb5d38c68eb23f0edcd2037f674aa20b3ad0df41ad3c0a52b197d9fd7543d47bbc89f45bf3455e7a551c0e2fbdb13f6b713a669363b2ec345a
+  data.tar.gz: 74c0911e5a65433aef1cd957262ea5d9074f8ff81cbd7bb017b1d6f76fd67cd2012ce3b6d2024a453752ed771fd9504b3441da7b2fefb1a468caffa25599b0d0

data/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-23
+
+### Added
+
+- Add `PermissionRuleSet` for composing default and project rules with
+  deny-first precedence, plus versioned JSON-safe snapshots for portable
+  host-owned rule storage.
+- Allow `ApprovalPolicy` to receive optional `project_rules:` while
+  preserving the existing `rules:` API.
 ## [0.2.0] - 2026-09-23
 
 ### Added

data/README.md

@@ -155,6 +155,31 @@ rules.allow "read_file", %r{/docs/}     # Regexp against the serialized args
 rules.allow "search"                    # any arguments
 ```
 
+### Project rule layers and snapshots
+
+Compose application defaults with host-selected project rules using
+`PermissionRuleSet`. A deny in either layer wins; otherwise a matching
+project decision overrides the default, and an unmatched project rule falls
+back to the default layer.
+
+```ruby
+defaults = Ask::Permissions::PermissionRules.new { deny :bash, /rm\s+-rf/ }
+project = Ask::Permissions::PermissionRules.new { allow :read_file }
+rules = Ask::Permissions::PermissionRuleSet.new(
+  default_rules: defaults,
+  project_rules: project
+)
+
+rules.classify(:bash, { command: "rm -rf /tmp" }) # => :deny
+rules.classify(:read_file)                        # => :allow
+```
+
+`PermissionRules#snapshot` and `PermissionRuleSet#snapshot` produce
+versioned, JSON-safe data restored with `.from_snapshot`. The gem does not
+persist rules or resolve project identity: the host must authorize and scope
+the storage itself. Pass a project's rules to `ApprovalPolicy` with
+`project_rules:` alongside default `rules:`.
+
 Introspection: `rules` and `dangerous_rules` (both in declaration order). Each entry is a `Rule` with `decision`, `declared_decision`, `effective_decision`, `tool_pattern`, `argument_pattern`, `dangerous`, plus the predicates `dangerous?` and `universal?` (unrestricted argument pattern — `argument_pattern` is `nil`, regardless of tool pattern) and the matchers `tool_matches?(name)`, `argument_matches?(args)`, and `matches?(name, args)`. `decision` and `declared_decision` always keep the decision as written at declaration time; `classify` returns `effective_decision`.
 
 ### Dangerous allow downgrade

data/lib/ask/permissions/approval_policy.rb

@@ -7,19 +7,26 @@ module Ask
       MODES = %i[full_access ask_before_changes read_only].freeze
       SIDE_EFFECT_SCOPES = %i[none session workspace project system external unknown].freeze
 
-      attr_reader :queue, :require_approval, :rules, :tools, :mode, :session_grants, :project_grants
+      attr_reader :queue, :require_approval, :rules, :tools, :mode, :session_grants, :project_grants,
+        :project_rules
 
       def initialize(queue:, require_approval: nil, rules: nil, tools: nil, mode: nil, session_grants: nil,
-        project_grants: nil)
+        project_grants: nil, project_rules: nil)
         raise ArgumentError, "Unknown permission mode: #{mode.inspect}" if mode && !MODES.include?(mode.to_sym)
 
         @queue = queue
         @require_approval = require_approval
-        @rules = rules
         @tools = tools
         @mode = mode&.to_sym
         @session_grants = session_grants
         @project_grants = project_grants
+        @project_rules = project_rules
+
+        @rules = if project_rules
+                   PermissionRuleSet.new(default_rules: rules, project_rules: project_rules)
+                 else
+                   rules
+                 end
       end
 
       def before_tool_call(tool_call, _context = nil)

data/lib/ask/permissions/permission_rule_set.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Ask
+  module Permissions
+    # Composes default and project rule layers into a single classifier.
+    #
+    # Resolution: any matched :deny from either layer wins. Otherwise the
+    # project decision wins over the default. If neither layer matches,
+    # classify returns nil.
+    class PermissionRuleSet
+      SNAPSHOT_VERSION = 1
+
+      attr_reader :default_rules, :project_rules
+
+      def initialize(default_rules: nil, project_rules: nil)
+        validate_layer!(default_rules, 'default_rules')
+        validate_layer!(project_rules, 'project_rules')
+
+        @default_rules = default_rules
+        @project_rules = project_rules
+      end
+
+      def classify(tool_name, args = nil)
+        default_decision = @default_rules&.classify(tool_name, args)
+        project_decision = @project_rules&.classify(tool_name, args)
+
+        return :deny if default_decision == :deny || project_decision == :deny
+
+        project_decision || default_decision
+      end
+
+      def snapshot
+        {
+          version: SNAPSHOT_VERSION,
+          default_rules: snapshot_layer(@default_rules, 'default_rules'),
+          project_rules: snapshot_layer(@project_rules, 'project_rules')
+        }
+      end
+
+      def self.from_snapshot(snapshot)
+        raise ArgumentError, 'Snapshot must be a Hash' unless snapshot.is_a?(Hash)
+        validate_snapshot_keys!(snapshot, %i[version default_rules project_rules])
+
+        version = snapshot_value(snapshot, :version)
+        raise ArgumentError, "Unsupported snapshot version: #{version.inspect}" unless version == 1
+
+        default_raw = snapshot_value(snapshot, :default_rules)
+        project_raw = snapshot_value(snapshot, :project_rules)
+        validate_snapshot_layer!(default_raw, 'default_rules')
+        validate_snapshot_layer!(project_raw, 'project_rules')
+
+        default_rules = default_raw ? PermissionRules.from_snapshot(default_raw) : nil
+        project_rules = project_raw ? PermissionRules.from_snapshot(project_raw) : nil
+
+        new(default_rules: default_rules, project_rules: project_rules)
+      end
+
+      private
+
+      def self.snapshot_value(hash, key)
+        return hash[key] if hash.key?(key)
+        return hash[key.to_s] if hash.key?(key.to_s)
+
+        raise ArgumentError, "Snapshot is missing #{key}"
+      end
+
+      def self.validate_snapshot_keys!(hash, allowed)
+        keys = hash.keys.map(&:to_s)
+        unknown = keys - allowed.map(&:to_s)
+        raise ArgumentError, "Snapshot has unknown fields: #{unknown.join(', ')}" unless unknown.empty?
+      end
+
+      def self.validate_snapshot_layer!(value, name)
+        return if value.nil? || value.is_a?(Hash)
+
+        raise ArgumentError, "Snapshot #{name} must be a Hash or nil"
+      end
+
+      def snapshot_layer(layer, name)
+        return nil unless layer
+        unless layer.respond_to?(:snapshot)
+          raise ArgumentError, "#{name} must respond to :snapshot to be serialized"
+        end
+
+        snapshot = layer.snapshot
+        raise ArgumentError, "#{name} snapshot must be a Hash" unless snapshot.is_a?(Hash)
+
+        snapshot
+      end
+
+      def validate_layer!(layer, name)
+        return if layer.nil?
+
+        unless layer.respond_to?(:classify)
+          raise ArgumentError, "#{name} must respond to :classify"
+        end
+      end
+    end
+  end
+end

data/lib/ask/permissions/permission_rules.rb

@@ -7,6 +7,9 @@ module Ask
   module Permissions
     # Evaluates tool-invocation rules and returns allow/ask/deny decisions.
     class PermissionRules
+      SNAPSHOT_VERSION = 1
+      VALID_DECISIONS = %w[allow ask deny].freeze
+      VALID_PATTERN_TYPES = %w[string symbol regexp all].freeze
       DANGEROUS_TOOLS = %i[bash code repl].freeze
 
       Rule = Data.define(
@@ -74,6 +77,58 @@ module Ask
         @mutex.synchronize { @dangerous_rules.dup }
       end
 
+      def snapshot
+        entries = rules.map do |rule|
+          entry = {
+            decision: rule.declared_decision.to_s,
+            tool_pattern: serialize_pattern(rule.tool_pattern)
+          }
+          entry[:argument_pattern] = serialize_pattern(rule.argument_pattern) if rule.argument_pattern
+          entry
+        end
+
+        { version: SNAPSHOT_VERSION, auto_allow_dangerous: @auto_allow_dangerous, rules: entries }
+      end
+
+      def self.from_snapshot(snapshot)
+        raise ArgumentError, 'Snapshot must be a Hash' unless snapshot.is_a?(Hash)
+        validate_snapshot_keys!(snapshot, %i[version auto_allow_dangerous rules], 'snapshot')
+
+        version = snapshot_value(snapshot, :version)
+        raise ArgumentError, "Unsupported snapshot version: #{version.inspect}" unless version == 1
+
+        auto_allow = snapshot_value(snapshot, :auto_allow_dangerous)
+        unless [true, false].include?(auto_allow)
+          raise ArgumentError, 'Snapshot auto_allow_dangerous must be true or false'
+        end
+
+        raw_rules = snapshot_value(snapshot, :rules)
+        raise ArgumentError, 'Snapshot rules must be an Array' unless raw_rules.is_a?(Array)
+
+        instance = new(auto_allow_dangerous: !!auto_allow)
+        raw_rules.each do |entry|
+          raise ArgumentError, 'Snapshot rule entry must be a Hash' unless entry.is_a?(Hash)
+          validate_snapshot_keys!(entry, %i[decision tool_pattern argument_pattern], 'rule entry')
+
+          decision_str = snapshot_value(entry, :decision)
+          raise ArgumentError, 'Rule entry missing decision' if decision_str.nil?
+          unless decision_str.is_a?(String) && VALID_DECISIONS.include?(decision_str)
+            raise ArgumentError, "Invalid decision: #{decision_str.inspect}"
+          end
+
+          tool_pattern_raw = snapshot_value(entry, :tool_pattern)
+          raise ArgumentError, 'Rule entry missing tool_pattern' if tool_pattern_raw.nil?
+          tool_pattern = deserialize_pattern(tool_pattern_raw)
+
+          argument_pattern_raw = optional_snapshot_value(entry, :argument_pattern)
+          argument_pattern = deserialize_pattern(argument_pattern_raw) unless argument_pattern_raw.nil?
+
+          instance.send(:register, decision_str.to_sym, tool_pattern, argument_pattern)
+        end
+
+        instance
+      end
+
       def classify(tool_name, args = nil)
         rule = rules.find { |candidate| candidate.matches?(tool_name, args) }
         rule&.effective_decision
@@ -93,6 +148,26 @@ module Ask
 
       private
 
+      def self.snapshot_value(hash, key)
+        return hash[key] if hash.key?(key)
+        return hash[key.to_s] if hash.key?(key.to_s)
+
+        raise ArgumentError, "Snapshot is missing #{key}"
+      end
+
+      def self.optional_snapshot_value(hash, key)
+        return hash[key] if hash.key?(key)
+        return hash[key.to_s] if hash.key?(key.to_s)
+
+        nil
+      end
+
+      def self.validate_snapshot_keys!(hash, allowed, name)
+        keys = hash.keys.map(&:to_s)
+        unknown = keys - allowed.map(&:to_s)
+        raise ArgumentError, "Snapshot #{name} has unknown fields: #{unknown.join(', ')}" unless unknown.empty?
+      end
+
       def register(decision, tool_pattern, argument_pattern)
         dangerous = dangerous_allow?(decision, tool_pattern, argument_pattern)
         effective = dangerous && !@auto_allow_dangerous ? :ask : decision
@@ -124,6 +199,77 @@ module Ask
 
         DANGEROUS_TOOLS.include?(tool_pattern.to_s.to_sym)
       end
+
+      REGEXP_FLAG_MAP = {
+        'i' => Regexp::IGNORECASE,
+        'm' => Regexp::MULTILINE,
+        'x' => Regexp::EXTENDED
+      }.freeze
+
+      def serialize_pattern(pattern)
+        case pattern
+        when Regexp
+          supported_options = Regexp::IGNORECASE | Regexp::MULTILINE | Regexp::EXTENDED
+          if (pattern.options & ~supported_options).nonzero?
+            raise ArgumentError, "Unsupported regexp options: #{pattern.options}"
+          end
+
+          flags_str = +''
+          flags_str << 'i' if (pattern.options & Regexp::IGNORECASE).nonzero?
+          flags_str << 'm' if (pattern.options & Regexp::MULTILINE).nonzero?
+          flags_str << 'x' if (pattern.options & Regexp::EXTENDED).nonzero?
+          { type: 'regexp', source: pattern.source, flags: flags_str }
+        when Symbol
+          pattern == :all ? { type: 'all' } : { type: 'symbol', value: pattern.to_s }
+        when String
+          { type: 'string', value: pattern }
+        else
+          raise ArgumentError, "Unsupported permission pattern type: #{pattern.class}"
+        end
+      end
+
+      def self.deserialize_pattern(raw)
+        raise ArgumentError, 'Pattern must be a Hash' unless raw.is_a?(Hash)
+
+        type = snapshot_value(raw, :type)
+        raise ArgumentError, "Invalid pattern type: #{type.inspect}" unless type.is_a?(String) && VALID_PATTERN_TYPES.include?(type)
+
+        allowed_keys = case type
+        when 'string', 'symbol' then %i[type value]
+        when 'regexp' then %i[type source flags]
+        when 'all' then %i[type]
+        end
+        validate_snapshot_keys!(raw, allowed_keys, 'pattern')
+
+        case type
+        when 'string'
+          value = snapshot_value(raw, :value)
+          raise ArgumentError, 'String pattern value must be a String' unless value.is_a?(String)
+
+          value
+        when 'symbol'
+          value = snapshot_value(raw, :value)
+          raise ArgumentError, 'Symbol pattern value must be a String' unless value.is_a?(String)
+
+          value.to_sym
+        when 'regexp'
+          source = snapshot_value(raw, :source)
+          flags_str = snapshot_value(raw, :flags)
+          raise ArgumentError, 'Regexp source must be a String' unless source.is_a?(String)
+          unless flags_str.is_a?(String) && flags_str.chars.uniq == flags_str.chars && flags_str.chars.all? { |flag| REGEXP_FLAG_MAP.key?(flag) }
+            raise ArgumentError, "Invalid regexp flags: #{flags_str.inspect}"
+          end
+
+          flags = flags_str.chars.reduce(0) { |sum, ch| sum | REGEXP_FLAG_MAP.fetch(ch) }
+          Regexp.new(source, flags)
+        when 'all'
+          :all
+        end
+      rescue RegexpError, TypeError => error
+        raise ArgumentError, "Invalid regexp pattern: #{error.message}"
+      end
+
+      private_class_method :deserialize_pattern
     end
   end
 end

data/lib/ask/permissions/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Permissions
-    VERSION = '0.2.0'
+    VERSION = '0.3.0'
   end
 end

data/lib/ask/permissions.rb

@@ -4,6 +4,7 @@ require 'ask/permissions/version'
 require 'ask/permissions/errors'
 require 'ask/permissions/tool_pattern'
 require 'ask/permissions/permission_rules'
+require 'ask/permissions/permission_rule_set'
 require 'ask/permissions/approval_queue'
 require 'ask/permissions/permissions'
 require 'ask/permissions/approval_policy'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-permissions
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -70,6 +70,7 @@ files:
 - lib/ask/permissions/approval_policy.rb
 - lib/ask/permissions/approval_queue.rb
 - lib/ask/permissions/errors.rb
+- lib/ask/permissions/permission_rule_set.rb
 - lib/ask/permissions/permission_rules.rb
 - lib/ask/permissions/permissions.rb
 - lib/ask/permissions/plan_mode_policy.rb