Class: Rigor::Plugin::TrustPolicy

Inherits:
Object
  • Object
show all
Defined in:
lib/rigor/plugin/trust_policy.rb

Overview

Declarative trust / I/O policy for the active plugin set. Pinned by [ADR-2 § “Plugin Trust and I/O Policy”](../../../docs/adr/2-extension-api.md): plugins are *trusted Ruby gems selected by the user, their Gemfile, or project configuration*; this class is the programmatic surface that documents that trust and lets the analyzer enforce read scope + network disablement at the documented edges.

The policy is **not a sandbox.** A plugin that uses raw ‘File.read` or `Net::HTTP` bypasses the policy — ADR-2 explicitly chooses documentation over forced isolation. The contract is: when plugins go through IoBoundary (the analyzer-side helper service slice 2 introduces), the boundary checks against this policy and feeds compliant reads into the cache descriptor for invalidation. Slices 3-6 wire plugin contributions through the boundary so the policy is the actual mechanism, not just paperwork.

## Fields

  • ‘trusted_gems`: gem names the user has authorised. Derived from the `plugins:` section of `.rigor.yml` plus any gems they reach transitively. Used today for documentation and future trust diagnostics.

  • ‘allowed_read_roots`: absolute paths plugin code may read from through the IoBoundary. The default set covers the project root, the project’s ‘signature_paths`, the active `Gemfile.lock`, and each trusted gem’s ‘Gem::Specification#full_gem_path`. The user extends this with `.rigor.yml`’s ‘plugins_io.allowed_paths:`.

  • ‘network_policy`: `:disabled` in slice 2; the only value accepted today. Plugin IoBoundary#open_url always raises while the policy is `:disabled`.

Constant Summary collapse

VALID_NETWORK_POLICIES = 
%i[disabled].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(trusted_gems: [], allowed_read_roots: [], network_policy: :disabled) ⇒ TrustPolicy

Returns a new instance of TrustPolicy.



43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/rigor/plugin/trust_policy.rb', line 43

def initialize(trusted_gems: [], allowed_read_roots: [], network_policy: :disabled)
  validate_network_policy!(network_policy)

  @trusted_gems = trusted_gems.map { |g| g.to_s.dup.freeze }.uniq.sort.freeze
  @allowed_read_roots = allowed_read_roots
                        .map { |path| File.expand_path(path).freeze }
                        .uniq
                        .sort
                        .freeze
  @network_policy = network_policy
  freeze
end

Instance Attribute Details

#allowed_read_roots ⇒ Object (readonly)

Returns the value of attribute allowed_read_roots.



41
42
43
 
# File 'lib/rigor/plugin/trust_policy.rb', line 41

def allowed_read_roots
  @allowed_read_roots
end

#network_policy ⇒ Object (readonly)

Returns the value of attribute network_policy.



41
42
43
 
# File 'lib/rigor/plugin/trust_policy.rb', line 41

def network_policy
  @network_policy
end

#trusted_gems ⇒ Object (readonly)

Returns the value of attribute trusted_gems.



41
42
43
 
# File 'lib/rigor/plugin/trust_policy.rb', line 41

def trusted_gems
  @trusted_gems
end

Instance Method Details

#allow_read?(path) ⇒ Boolean

Returns true when the absolute path falls inside any allowed read root. Symlinks are resolved through ‘File.expand_path` only (no `realpath`); plugins with adversarial intent are out of scope per ADR-2.

Parameters:

  • path (String)

Returns:

  • (Boolean) —

    true when the absolute path falls inside any allowed read root. Symlinks are resolved through ‘File.expand_path` only (no `realpath`); plugins with adversarial intent are out of scope per ADR-2.



61
62
63
64
 
# File 'lib/rigor/plugin/trust_policy.rb', line 61

def allow_read?(path)
  absolute = File.expand_path(path.to_s)
  @allowed_read_roots.any? { |root| inside?(absolute, root) }
end

#gem_trusted?(name) ⇒ Boolean

Returns:

  • (Boolean) 


70
71
72
 
# File 'lib/rigor/plugin/trust_policy.rb', line 70

def gem_trusted?(name)
  @trusted_gems.include?(name.to_s)
end

#network_allowed? ⇒ Boolean

Returns:

  • (Boolean) 


66
67
68
 
# File 'lib/rigor/plugin/trust_policy.rb', line 66

def network_allowed?
  @network_policy != :disabled
end

#to_h ⇒ Object 



74
75
76
77
78
79
80
 
# File 'lib/rigor/plugin/trust_policy.rb', line 74

def to_h
  {
    "trusted_gems" => trusted_gems,
    "allowed_read_roots" => allowed_read_roots,
    "network_policy" => network_policy.to_s
  }
end