reeve 0.0.1 → 0.1.0

data/lib/reeve/audit/recorder.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    # The one write path into the ledger (FR-008).
+    #
+    # The envelope calls this from an `ensure` block and expects it to raise on failure —
+    # Constitution II makes a failed write a failed call unless the host has opted into a
+    # degraded mode. Everything here is therefore synchronous: no queue, no thread, no
+    # ActiveJob. An asynchronous ledger cannot be relied on and would make FR-012
+    # unenforceable.
+    #
+    # The insert runs in `requires_new: true`, which is what makes the trace survive a
+    # tool body that opens a transaction and rolls it back (R5) — the case this was built
+    # for, and the one it does solve.
+    #
+    # What it does **not** do, corrected after review: `requires_new` is a SAVEPOINT, not
+    # an independent transaction. If the host has already opened a transaction *around*
+    # the invocation — a controller or middleware that wraps each request, or a test suite
+    # using transactional fixtures — the savepoint is released into that transaction, and
+    # a later rollback takes the ledger row with it. The write reports success and the
+    # envelope has no way to learn otherwise, so the invocation returns records with no
+    # surviving trace. The comment here previously claimed independence outright; it did
+    # not have it.
+    #
+    # A genuinely independent write needs a second connection, and that is not portable:
+    # on SQLite the enclosing transaction holds the write lock, so a second connection
+    # blocks until it times out. Rather than fail every call on the databases where
+    # isolation is impossible, the recorder detects the enclosing transaction and warns
+    # that the guarantee is suspended for that call. A host that needs durability under a
+    # wrapping transaction supplies its own `audit_recorder` — writing to a separate
+    # connection, a queue, or an append-only log — which is what that setting is for.
+    #
+    # The other known limit, unchanged: on a single connection there is a narrow window
+    # where the tool's data commits and the ledger write then fails. The caller learns by
+    # exception, but the data change has already landed.
+    class Recorder
+      # Free-form text from a policy or an exception message. Capped rather than trusted:
+      # it is the one column whose length the host does not control.
+      DETAIL_LIMIT = 1000
+
+      def self.record(attributes)
+        new.record(attributes)
+      end
+
+      def initialize(entry_class: Entry, config: nil)
+        @entry_class = entry_class
+        @config = config
+      end
+
+      # Returns the entry. Raises if the row could not be written, so the envelope can
+      # fail the invocation.
+      def record(attributes)
+        row = row_for(attributes)
+        warn_about_enclosing_transaction(row[:invocation_id])
+
+        entry_class.transaction(requires_new: true) do
+          entry_class.create!(row)
+        end
+      rescue ActiveRecord::RecordNotUnique, ActiveRecord::RecordInvalid => e
+        # A replayed invocation is the same invocation. One row per invocation_id means
+        # a retry is a no-op insert, never a second row (contracts/audit-entry.md).
+        existing = entry_class.find_by(invocation_id: row[:invocation_id])
+        raise e if existing.nil?
+
+        existing
+      end
+
+      private
+
+      attr_reader :entry_class
+
+      def config
+        @config || Reeve.config
+      end
+
+      def row_for(attributes)
+        ids, count, truncated = identifiers(attributes)
+
+        identity(attributes).merge(
+          arguments: redact(attributes),
+          outcome: attributes[:outcome].to_s,
+          rule: attributes[:rule],
+          detail: detail(attributes),
+          record_type: attributes[:record_type],
+          record_ids: ids,
+          record_count: count,
+          truncated: truncated,
+          derived: attributes[:derived] ? true : false,
+          guard: blank?(attributes[:guard]) ? "policy" : attributes[:guard].to_s,
+          duration_ms: attributes[:duration_ms],
+          metadata: attributes[:metadata]
+        )
+      end
+
+      def identity(attributes)
+        {
+          invocation_id: attributes[:invocation_id],
+          occurred_at: attributes[:occurred_at],
+          agent_id: agent_id(attributes),
+          agent_name: attributes[:agent_name],
+          principal_type: attributes[:principal_type],
+          principal_id: attributes[:principal_id]&.to_s,
+          tool_name: attributes[:tool_name]
+        }
+      end
+
+      # An unidentifiable agent is recorded as unknown, never dropped: attribution is not
+      # authorization, and a row that names no agent still answers most of the question.
+      def agent_id(attributes)
+        blank?(attributes[:agent_id]) ? Context::UNKNOWN_AGENT_ID : attributes[:agent_id]
+      end
+
+      def redact(attributes)
+        Redactor.for(attributes[:tool_name], config: config).call(attributes[:arguments])
+      end
+
+      # FR-014: identifiers are capped, never silently dropped — the count stays true and
+      # the row says it was truncated. The scoper caps first; this is the backstop that
+      # makes the guarantee hold at the ledger regardless of who produced the list.
+      def identifiers(attributes)
+        ids = Array(attributes[:record_ids]).map(&:to_s)
+        count = attributes[:record_count] || ids.size
+        truncated = attributes[:truncated] ? true : false
+        limit = config.max_recorded_ids
+
+        return [ids, count, truncated] unless ids.size > limit
+
+        [ids.first(limit), [count, ids.size].max, true]
+      end
+
+      def detail(attributes)
+        value = attributes[:detail]
+        return nil if blank?(value)
+
+        value.to_s[0, DETAIL_LIMIT]
+      end
+
+      # The host's transaction, not the tool's: the tool's own transaction is nested
+      # inside this write and is exactly what `requires_new` protects against.
+      def warn_about_enclosing_transaction(invocation_id)
+        return unless enclosing_transaction?
+
+        message = "reeve: invocation #{invocation_id} was recorded inside a transaction " \
+                  "the host opened around it, so the ledger row will be rolled back with " \
+                  "it. Configure Reeve.config.audit_recorder with a recorder that writes " \
+                  "outside this transaction if the trace must survive."
+        logger = config.logger
+        logger ? logger.warn(message) : Kernel.warn(message)
+      end
+
+      def enclosing_transaction?
+        entry_class.connection.transaction_open?
+      rescue StandardError
+        false
+      end
+
+      def blank?(value)
+        value.nil? || value.to_s.strip.empty?
+      end
+    end
+  end
+end

data/lib/reeve/audit/redactor.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Audit
+    # Removes declared-sensitive values from the arguments before they are written
+    # (FR-011).
+    #
+    # Names always survive: an entry that cannot say *which* argument was passed answers
+    # nothing after an incident. Values of declared names are replaced, recursively,
+    # wherever they appear. Matching is on the name, never on the value — pattern-sniffing
+    # a compliance artifact both misses and over-matches (R6).
+    #
+    # The input is never mutated and never stored: the redacted hash is a new structure,
+    # so no unredacted copy exists downstream of this object.
+    class Redactor
+      MARKER = "[REDACTED]"
+
+      # The names declared globally, plus the ones this tool's own guard declared.
+      def self.for(tool_name, config: Reeve.config, registry: Audit.guard_registry)
+        new(Array(config.redact_arguments) + tool_names(tool_name, registry))
+      end
+
+      def self.tool_names(tool_name, registry)
+        return [] unless registry.respond_to?(:guard_for)
+
+        guard = registry.guard_for(tool_name)
+        return [] unless guard.respond_to?(:redacted_arguments)
+
+        Array(guard.redacted_arguments)
+      end
+      private_class_method :tool_names
+
+      def initialize(names, marker: MARKER)
+        @names  = Array(names).map { |name| name.to_s.downcase }.uniq.freeze
+        @marker = marker
+      end
+
+      def call(arguments)
+        return {} if arguments.nil?
+
+        redact_hash(arguments)
+      end
+
+      private
+
+      attr_reader :names, :marker
+
+      def redact_hash(hash)
+        hash.each_with_object({}) do |(key, value), result|
+          result[key] = sensitive?(key) ? marker : redact(value)
+        end
+      end
+
+      def redact(value)
+        case value
+        when Hash  then redact_hash(value)
+        when Array then value.map { |element| redact(element) }
+        else value
+        end
+      end
+
+      def sensitive?(key)
+        names.include?(key.to_s.downcase)
+      end
+    end
+  end
+end

data/lib/reeve/audit.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative "../reeve"
+
+begin
+  require "active_record"
+rescue LoadError => e
+  raise Reeve::ConfigurationError,
+        "reeve/audit needs activerecord, which could not be loaded (#{e.message}). " \
+        "Add activerecord to your Gemfile, or configure a non-ActiveRecord " \
+        "Reeve.config.audit_recorder instead."
+end
+
+module Reeve
+  # The append-only ledger: one row per guarded invocation, allowed or denied
+  # (Constitution II, FR-008).
+  #
+  # This file is the opt-in boundary. `require "reeve"` must keep working in a bare Ruby
+  # process with no ActiveRecord (SC-008), so nothing here is loaded by the core — a host
+  # (or the generated initializer) requires "reeve/audit" when it wants the table-backed
+  # recorder.
+  #
+  #   require "reeve/audit"
+  #
+  #   Reeve::Audit::Query.for_principal(user)
+  #                      .for_agent("claude-desktop")
+  #                      .between(1.week.ago, Time.current)
+  #                      .pluck(:tool_name, :record_type, :record_ids, :outcome, :rule)
+  #
+  # == What this module guarantees
+  #
+  # * exactly one row per invocation, allowed or denied — `invocation_id` is unique, and
+  #   a replayed invocation is a no-op insert rather than a second row;
+  # * `rule` is never null: every row explains itself;
+  # * arguments are post-redaction, and no unredacted copy is written anywhere;
+  # * `record_count` stays true even when `record_ids` was capped, and `truncated` says so;
+  # * `occurred_at` is invocation time, not write time;
+  # * no public method updates or deletes an entry.
+  #
+  # == What it does not
+  #
+  # * It does not stop a database superuser, a migration, or raw SQL from rewriting the
+  #   table. Immutability is enforced at the library level; the generated migration
+  #   documents the `GRANT INSERT, SELECT` that enforces the rest where it can actually be
+  #   enforced, and the gem makes no stronger claim than that.
+  # * No retention, rotation or archival in v1 — the table is host-owned and the host's
+  #   existing policies apply.
+  # * No cryptographic chaining or tamper-evidence in v1. If that lands it arrives as a
+  #   nullable column, which the audit-entry contract's versioning already permits.
+  module Audit
+    # The version of the audit-entry shape, as documented in
+    # specs/001-guardrails-core/contracts/audit-entry.md (FR-015). Adding a nullable
+    # column is a MINOR change and leaves this alone; removing or renaming a column, or
+    # changing what a value means, is MAJOR and bumps it.
+    CONTRACT_VERSION = 1
+
+    TABLE_NAME = "reeve_audit_entries"
+
+    class << self
+      # Where per-tool redaction declarations come from: the authorization registry, if
+      # the authorization module is loaded. Duck-typed and optional on purpose — the
+      # ledger is useful on its own, and a host running audit without guards should get
+      # the global redaction list rather than a NameError.
+      def guard_registry
+        return nil unless Reeve.respond_to?(:registry)
+
+        Reeve.registry
+      end
+
+      # contracts/configuration.md documents `audit_recorder` as defaulting to nil, "which
+      # resolves to Reeve::Audit::Recorder at invocation time — the default cannot be the
+      # constant itself, since the core loads without ActiveRecord". This is that
+      # resolution, performed at the first moment the constant is known to exist: the
+      # require of this file. A host that named its own recorder keeps it.
+      def install!(config = Reeve.config)
+        config.audit_recorder ||= Recorder
+        config
+      end
+    end
+  end
+end
+
+require_relative "audit/redactor"
+require_relative "audit/entry"
+require_relative "audit/recorder"
+require_relative "audit/query"
+
+Reeve::Audit.install!

data/lib/reeve/authorization/adapter.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Authorization
+    # Chooses the adapter a policy speaks through, and refuses declarations no adapter
+    # can serve — at declaration time, so the developer learns immediately rather than on
+    # the first denial in production (Constitution VI).
+    module Adapter
+      BUILT_IN = { plain: Adapters::Plain, pundit: Adapters::Pundit }.freeze
+
+      module_function
+
+      def resolve(policy, setting = Reeve.config.policy_adapter)
+        case setting
+        when :plain  then Adapters::Plain.new
+        when :pundit then Adapters::Pundit.new
+        when :auto   then auto_resolve(policy)
+        else setting # a host-supplied adapter object; Configuration validated its protocol
+        end
+      end
+
+      def resolve_name(policy, setting = Reeve.config.policy_adapter)
+        return setting unless setting == :auto
+
+        Adapters::Pundit.supports?(policy) ? :pundit : :plain
+      end
+
+      # Raises unless some adapter can serve this policy. Called from `guard_with`.
+      def validate!(policy, setting = Reeve.config.policy_adapter)
+        return true if supported?(policy, setting)
+
+        raise ConfigurationError, unsupported_message(policy, setting)
+      end
+
+      def supported?(policy, setting = Reeve.config.policy_adapter)
+        case setting
+        when :plain  then Adapters::Plain.supports?(policy)
+        when :pundit then Adapters::Pundit.supports?(policy)
+        when :auto   then Adapters::Pundit.supports?(policy) || Adapters::Plain.supports?(policy)
+        else true # a custom adapter is trusted to know its own policies
+        end
+      end
+
+      def auto_resolve(policy)
+        Adapters::Pundit.supports?(policy) ? Adapters::Pundit.new : Adapters::Plain.new
+      end
+
+      def unsupported_message(policy, setting)
+        described = policy.respond_to?(:name) && policy.name ? policy.name : policy.inspect
+        missing = Adapters::Plain.missing_methods(policy).map do |method|
+          "##{method}"
+        end.join(" and ")
+
+        "#{described} cannot be used as a reeve policy (policy_adapter is #{setting.inspect}). " \
+          "A plain policy must respond to #{missing.empty? ? '#authorize and #scope' : missing}; " \
+          "a Pundit policy must define a query method and a Scope class."
+      end
+    end
+  end
+
+  # Reopened to answer one question the adapter layer owns: which adapter a policy will
+  # actually be served by. Kept here rather than in the kernel so configuration.rb stays
+  # free of any knowledge of policies.
+  class Configuration
+    # Which adapter `:auto` actually chose. Documented in contracts/policy-adapter.md so
+    # the choice is never a mystery, and so the compliance suite can assert on it.
+    def resolved_policy_adapter(policy = nil)
+      Authorization::Adapter.resolve_name(policy, policy_adapter)
+    end
+  end
+end

data/lib/reeve/authorization/adapters/plain.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Authorization
+    module Adapters
+      # Plain policy objects — always available, no dependency on anything.
+      #
+      #   class InvoicePolicy
+      #     def self.authorize(principal, action, record) = ...
+      #     def self.scope(principal, relation) = relation.where(owner: principal)
+      #   end
+      class Plain
+        REQUIRED_METHODS = %i[authorize scope].freeze
+
+        def self.supports?(policy)
+          REQUIRED_METHODS.all? { |method| policy.respond_to?(method) }
+        end
+
+        def self.missing_methods(policy)
+          REQUIRED_METHODS.reject { |method| policy.respond_to?(method) }
+        end
+
+        def authorize(principal:, policy:, action:, record: nil)
+          rule = rule_for(policy, action)
+          allowed = policy.authorize(principal, action, record)
+
+          allowed ? Decision.allow(rule: rule) : Decision.deny(rule: rule)
+        end
+
+        def scope(principal:, policy:, relation:)
+          scoped = policy.scope(principal, relation)
+          return scoped unless scoped.nil?
+
+          # A nil scope is a policy that did not answer. Answering "everything" would be
+          # the dangerous reading, so this is an error rather than a fallback.
+          raise Error, "#{rule_for(policy, :scope)} returned nil; a scope must return a relation"
+        end
+
+        def scope_rule(policy)
+          rule_for(policy, :scope)
+        end
+
+        # A tool may return more than the type its declared policy governs. Rather than
+        # denying every mixed result, reeve looks for the conventional `<Model>Policy`
+        # for the other types — and denies when there is not one (unknown_record_type).
+        def policy_for(record_class)
+          name = "#{record_class.name}Policy"
+          return nil unless Object.const_defined?(name)
+
+          policy = Object.const_get(name)
+          self.class.supports?(policy) ? policy : nil
+        rescue NameError
+          nil
+        end
+
+        private
+
+        def rule_for(policy, action)
+          name = policy.respond_to?(:name) && policy.name ? policy.name : policy.class.name
+          "#{name}##{action}"
+        end
+      end
+    end
+  end
+end

data/lib/reeve/authorization/adapters/pundit.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Authorization
+    module Adapters
+      # Pundit policies, bridged rather than depended on. Pundit itself is never required
+      # by this gem (Constitution IV); this file only speaks its conventions, and reports
+      # that it supports nothing when Pundit is absent.
+      #
+      #   class InvoicePolicy
+      #     def index? = ...
+      #     class Scope < ApplicationPolicy::Scope
+      #       def resolve = scope.where(owner: user)
+      #     end
+      #   end
+      class Pundit
+        def self.pundit_loaded?
+          defined?(::Pundit) ? true : false
+        end
+
+        def self.supports?(policy)
+          return false unless pundit_loaded?
+          return false unless policy.is_a?(Class)
+
+          # `false` matters: const_defined? otherwise walks up to Object, where any
+          # top-level Scope constant would make an unrelated policy look Pundit-shaped.
+          policy.const_defined?(:Scope, false) &&
+            policy.public_instance_methods.any? { |method| method.to_s.end_with?("?") }
+        end
+
+        def self.missing_methods(policy)
+          return [] if supports?(policy)
+          return [:Scope] if policy.is_a?(Class) && !policy.const_defined?(:Scope, false)
+
+          %i[query_method Scope]
+        end
+
+        def authorize(principal:, policy:, action:, record: nil)
+          query = "#{action}?"
+          rule = "#{policy.name}##{query}"
+          subject = record || inferred_subject(policy)
+
+          if policy.new(principal,
+                        subject).public_send(query)
+            Decision.allow(rule: rule)
+          else
+            Decision.deny(rule: rule)
+          end
+        end
+
+        def scope(principal:, policy:, relation:)
+          scoped = policy::Scope.new(principal, relation).resolve
+          return scoped unless scoped.nil?
+
+          raise Error, "#{scope_rule(policy)} returned nil; a scope must return a relation"
+        end
+
+        def scope_rule(policy)
+          "#{policy.name}::Scope"
+        end
+
+        # Pundit's own convention, which is what makes per-type scoping of a mixed result
+        # possible at all: Invoice => InvoicePolicy.
+        def policy_for(record_class)
+          name = "#{record_class.name}Policy"
+          Object.const_defined?(name) ? Object.const_get(name) : nil
+        rescue NameError
+          nil
+        end
+
+        private
+
+        # Pundit policies are constructed with a record; for an index-style check there is
+        # no record yet, so the class stands in — the same thing `authorize Invoice` does.
+        def inferred_subject(policy)
+          name = policy.name.to_s.sub(/Policy\z/, "")
+          Object.const_defined?(name) ? Object.const_get(name) : nil
+        rescue NameError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/reeve/authorization/authorizer.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Authorization
+    # The envelope's `authorizer` collaborator: turns a guard declaration plus a principal
+    # into a Decision, through whichever adapter the policy speaks.
+    #
+    # It deliberately does not rescue. The envelope converts a raising policy into
+    # `policy_error` and fails closed; swallowing it here would hide which policy broke.
+    class Authorizer
+      def authorize(context:, guard:)
+        adapter = Adapter.resolve(guard.policy)
+
+        adapter.authorize(
+          principal: context.principal,
+          policy: guard.policy,
+          action: guard.action,
+          record: nil
+        )
+      end
+    end
+  end
+end

data/lib/reeve/authorization/current.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Reeve
+  module Authorization
+    # The invocation in progress on this thread.
+    #
+    # `scoped(Model)` is called from inside a tool body, which has no reference to the
+    # envelope, so the envelope's caller publishes the state here and clears it in an
+    # ensure. Fiber-local storage (Thread#[]) rather than thread-global, so concurrent
+    # invocations — the normal case for an MCP server — cannot see each other's principal.
+    module Current
+      KEY = :reeve_current_invocation
+
+      module_function
+
+      def state
+        Thread.current[KEY]
+      end
+
+      def start(context:, declaration:, adapter:)
+        previous = state
+        Thread.current[KEY] =
+          State.new(context: context, declaration: declaration, adapter: adapter)
+        previous
+      end
+
+      def finish(previous = nil)
+        Thread.current[KEY] = previous
+      end
+
+      def with(context:, declaration:, adapter:)
+        previous = start(context: context, declaration: declaration, adapter: adapter)
+        yield(state)
+      ensure
+        finish(previous)
+      end
+
+      def active?
+        !state.nil?
+      end
+
+      # Mutable for exactly two reasons: recording that `scoped` was used, and the size of
+      # what it scoped. Everything else about an invocation is fixed when it starts.
+      class State
+        attr_reader :context, :declaration, :adapter
+        attr_accessor :scoped_source_count
+
+        def initialize(context:, declaration:, adapter:)
+          @context = context
+          @declaration = declaration
+          @adapter = adapter
+          @scoped_used = false
+          @scoped_source_count = nil
+        end
+
+        def scoped_used!
+          @scoped_used = true
+        end
+
+        def scoped_used?
+          @scoped_used
+        end
+      end
+    end
+  end
+end