textus 0.51.0 → 0.53.0

data/lib/textus/gate/auth.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Textus
+  class Gate
+    class Auth
+      FLOOR = {
+        put: %w[lane_writable_by],
+        key_delete: %w[lane_writable_by],
+        key_mv: %w[lane_writable_by],
+        accept: %w[author_held],
+        reject: %w[author_held],
+        propose: %w[lane_writable_by],
+        key_mv_prefix: %w[lane_writable_by],
+        key_delete_prefix: %w[lane_writable_by],
+      }.freeze
+
+      AuthContext = Struct.new(
+        :actor, :actor_caps, :lane_verb,
+        :action, :target, :envelope,
+        :mentry, :manifest,
+        keyword_init: true
+      )
+
+      def initialize(container)
+        @manifest = container.manifest
+        @schemas = container.schemas
+      end
+
+      # Command-based check (new Gate path).
+      def check!(cmd)
+        key = extract_key(cmd)
+        return unless key
+
+        evaluate_predicates(
+          action: command_to_action(cmd),
+          actor: cmd.role.to_s,
+          key: key,
+          envelope: nil,
+          extra: {},
+        )
+      end
+
+      # Backward-compatible check for inline action auth (accept, put, etc.).
+      def check_action!(action:, actor:, key:, envelope: nil, extra: {})
+        evaluate_predicates(
+          action: action.to_sym,
+          actor: actor,
+          key: key,
+          envelope: envelope,
+          extra: extra,
+        )
+      end
+
+      def self.command_to_verb
+        @command_to_verb ||= Textus::Gate::VERB_COMMAND.invert.freeze
+      end
+
+      private
+
+      def command_to_action(cmd)
+        self.class.command_to_verb.fetch(cmd.class) do
+          raise Textus::UsageError.new("unmapped command: #{cmd.class}")
+        end
+      end
+
+      def evaluate_predicates(action:, actor:, key:, envelope:, extra:)
+        mentry = @manifest.resolver.resolve(key).entry
+        lane_verb = @manifest.policy.verb_for_lane(mentry.lane.to_s)
+        actor_caps = Set.new(@manifest.data.role_caps.fetch(actor, []))
+
+        ctx = AuthContext.new(
+          actor:, actor_caps:, lane_verb:,
+          action:, target: key, envelope:,
+          mentry:, manifest: @manifest
+        )
+
+        failures = []
+        floor_preds = FLOOR.fetch(action, [])
+        rule_preds = rule_declared_predicates(action, key)
+        (floor_preds + rule_preds).uniq.each do |pred|
+          result = evaluate(pred, ctx, extra)
+          next if result[:pass]
+          raise result[:error] if result[:error]
+
+          failures << [pred, result[:reason]]
+        end
+        raise Textus::GuardFailed.new(failures) unless failures.empty?
+      end
+
+      def extract_key(cmd)
+        if cmd.respond_to?(:pending_key)
+          cmd.pending_key
+        elsif cmd.respond_to?(:key)
+          cmd.key
+        end
+      end
+
+      def rule_declared_predicates(action, key)
+        guard_map = @manifest.rules.for(key).guard
+        return [] if guard_map.nil?
+
+        Array(guard_map[action.to_s])
+      end
+
+      def evaluate(pred_name, ctx, extra)
+        case pred_name
+        when "lane_writable_by"  then evaluate_lane_writable_by(ctx)
+        when "author_held"       then evaluate_author_held(ctx)
+        when "target_is_canon"   then evaluate_target_is_canon(ctx)
+        when "etag_match"        then evaluate_etag_match(ctx, extra)
+        when "schema_valid"      then evaluate_schema_valid(ctx)
+        when "fresh_within"      then { pass: true }
+        else raise Textus::UsageError.new("unknown predicate '#{pred_name}'")
+        end
+      end
+
+      def evaluate_lane_writable_by(ctx)
+        pass = ctx.actor_caps.include?(ctx.lane_verb.to_s)
+        return { pass: true } if pass
+
+        holders = @manifest.policy.roles_with_capability(ctx.lane_verb.to_s)
+        { pass: false, error: Textus::WriteForbidden.new(ctx.mentry.key, ctx.mentry.lane, verb: ctx.lane_verb, holders:) }
+      end
+
+      def evaluate_author_held(ctx)
+        holders = @manifest.policy.roles_with_capability("author")
+        pass = holders.include?(ctx.actor.to_s)
+        reason = if pass
+                   nil
+                 elsif holders.empty?
+                   "no role holds the 'author' capability; #{ctx.action} is disabled"
+                 else
+                   "role '#{ctx.actor}' lacks the 'author' capability (held by: #{holders.join(", ")})"
+                 end
+        { pass:, reason: }
+      end
+
+      def evaluate_target_is_canon(ctx)
+        kind = @manifest.policy.declared_kind(ctx.mentry.lane.to_s)
+        pass = kind == :canon
+        { pass:, reason: pass ? nil : "target lane '#{ctx.mentry.lane}' is not canon (kind: #{kind})" }
+      end
+
+      def evaluate_etag_match(ctx, extra)
+        if_etag = extra[:if_etag]
+        return { pass: true } if if_etag.nil?
+
+        current = ctx.envelope&.etag
+        pass = current.nil? || current == if_etag
+        { pass:, error: pass ? nil : Textus::EtagMismatch.new(ctx.target, if_etag, current) }
+      end
+
+      def evaluate_schema_valid(ctx)
+        return { pass: true } unless ctx.envelope
+
+        schema_ref = ctx.mentry.schema
+        return { pass: true } unless schema_ref
+
+        schema = @schemas.fetch_or_nil(schema_ref)
+        return { pass: true } unless schema
+
+        frontmatter = ctx.envelope.meta&.dig("_meta") || ctx.envelope.meta || {}
+        begin
+          schema.validate!(frontmatter)
+          { pass: true }
+        rescue Textus::SchemaViolation => e
+          { pass: false, reason: schema_reason(e) }
+        end
+      end
+
+      def schema_reason(err)
+        d = err.details
+        return err.message.dup unless d.is_a?(Hash)
+        return "missing required fields: #{Array(d["missing"]).join(", ")}" if d["missing"]
+        return "field '#{d["field"]}': #{d["reason"]}" if d["field"]
+
+        err.message.dup
+      end
+    end
+  end
+end

data/lib/textus/gate.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Textus
+  class Gate
+    VERB_COMMAND = {
+      get: Textus::Command::Get,
+      put: Textus::Command::Put,
+      propose: Textus::Command::Propose,
+      key_delete: Textus::Command::KeyDelete,
+      key_mv: Textus::Command::KeyMv,
+      accept: Textus::Command::Accept,
+      reject: Textus::Command::Reject,
+      enqueue: Textus::Command::Enqueue,
+      list: Textus::Command::List,
+      where: Textus::Command::Where,
+      uid: Textus::Command::Uid,
+      blame: Textus::Command::Blame,
+      audit: Textus::Command::Audit,
+      deps: Textus::Command::Deps,
+      rdeps: Textus::Command::Rdeps,
+      pulse: Textus::Command::Pulse,
+      rule_explain: Textus::Command::RuleExplain,
+      rule_list: Textus::Command::RuleList,
+      rule_lint: Textus::Command::RuleLint,
+      published: Textus::Command::Published,
+      schema_show: Textus::Command::SchemaShow,
+      doctor: Textus::Command::Doctor,
+      boot: Textus::Command::Boot,
+      jobs: Textus::Command::Jobs,
+      data_mv: Textus::Command::DataMv,
+      key_mv_prefix: Textus::Command::KeyMvPrefix,
+      key_delete_prefix: Textus::Command::KeyDeletePrefix,
+      drain: Textus::Command::Drain,
+    }.freeze
+
+    ROUTES = {
+      Command::Get => [Textus::Action::Get],
+      Command::Put => [Textus::Action::Put],
+      Command::Propose => [Textus::Action::Propose],
+      Command::KeyDelete => [Textus::Action::KeyDelete],
+      Command::KeyMv => [Textus::Action::KeyMv],
+      Command::Accept => [Textus::Action::Accept],
+      Command::Reject => [Textus::Action::Reject],
+      Command::Enqueue => [Textus::Action::Enqueue],
+      Command::List => [Textus::Action::List],
+      Command::Where => [Textus::Action::Where],
+      Command::Uid => [Textus::Action::Uid],
+      Command::Blame => [Textus::Action::Blame],
+      Command::Audit => [Textus::Action::Audit],
+      Command::Deps => [Textus::Action::Deps],
+      Command::Rdeps => [Textus::Action::Rdeps],
+      Command::Pulse => [Textus::Action::Pulse],
+      Command::RuleExplain => [Textus::Action::RuleExplain],
+      Command::RuleList => [Textus::Action::RuleList],
+      Command::RuleLint => [Textus::Action::RuleLint],
+      Command::Published => [Textus::Action::Published],
+      Command::SchemaShow => [Textus::Action::SchemaEnvelope],
+      Command::Doctor => [Textus::Action::Doctor],
+      Command::Boot => [Textus::Action::Boot],
+      Command::Jobs => [Textus::Action::Jobs],
+      Command::DataMv => [Textus::Action::DataMv],
+      Command::KeyMvPrefix => [Textus::Action::KeyMvPrefix],
+      Command::KeyDeletePrefix => [Textus::Action::KeyDeletePrefix],
+      Command::Drain => [Textus::Action::Drain],
+    }.freeze
+
+    def initialize(container)
+      @container = container
+    end
+
+    def dispatch(cmd, correlation_id: nil)
+      cmd = normalize_propose_key(cmd, @container) if cmd.is_a?(Command::Propose)
+      action_classes = ROUTES.fetch(cmd.class) do
+        raise Textus::UsageError.new("unknown command: #{cmd.class}")
+      end
+
+      Gate::Auth.new(@container).check!(cmd)
+      call_obj = build_call(cmd, correlation_id: correlation_id)
+      results = action_classes.map { |klass| run_action(klass, cmd, @container, call_obj) }
+      results.length == 1 ? results.first : results
+    end
+
+    private
+
+    def normalize_propose_key(cmd, container)
+      return cmd if cmd.pending_key
+
+      zone = container.manifest.policy.propose_lane_for(cmd.role.to_s)
+      cmd.with(pending_key: zone ? "#{zone}.#{cmd.key}" : nil)
+    end
+
+    def run_action(klass, cmd, container, call_obj)
+      action = klass.new(**extract_kwargs(klass, cmd))
+      action.call(container:, call: call_obj)
+    end
+
+    def extract_kwargs(klass, cmd)
+      params = klass.instance_method(:initialize).parameters
+      accepts_keyrest = params.any? { |t, _| t == :keyrest }
+      param_set = params.to_set { |_t, n| n }
+      cmd.members.each_with_object({}) do |m, h|
+        next unless accepts_keyrest || param_set.include?(m)
+
+        val = cmd.public_send(m)
+        h[m] = val unless val.nil?
+      end
+    end
+
+    def build_call(cmd, correlation_id: nil)
+      dry_run = cmd.respond_to?(:dry_run) ? !cmd.dry_run.nil? : false
+      Textus::Call.build(role: cmd.role, dry_run:, correlation_id: correlation_id)
+    end
+  end
+end

data/lib/textus/init/templates/machine_intake.rb

@@ -1,45 +1,49 @@
-# .textus/hooks/machine_intake.rb
+# .textus/steps/fetch/machine_intake.rb
 # Scaffolded by `textus init` — CUSTOMIZE FREELY, or delete the feeds.machines
 # entry from manifest.yaml if you don't want it.
-# Feeds a per-host SNAPSHOT into feeds.machines.<host> on `textus reconcile`
+# Feeds a per-host SNAPSHOT into feeds.machines.<host> on `textus drain`
 # (never on the per-turn boot/pulse path). It is NESTED so it grows to a fleet: the
 # `local` leaf scans THIS host; add ssh hosts with the cookbook recipe
 # (docs/cookbook/environment-scan.md). tracked:false → gitignored. Keep this an
 # ALLOWLIST of versions and counts — NEVER secrets, raw `env`, or package lists.
-Textus.hook do |reg|
-  reg.on(:resolve_handler, :machines) do |config:, args:, **|
-    machine = args[:leaf_segments].first or
-      raise "machines intake needs a host leaf, e.g. the 'local' in feeds.machines.local"
-    spec = (config["machines"] || {}).fetch(machine) { raise "unknown machine: #{machine}" }
-    unless (spec["via"] || "local").to_s == "local"
-      raise "machine #{machine}: only `via: local` is scaffolded — see " \
-            "docs/cookbook/environment-scan.md for the SSH (remote) fan-out"
-    end
+module Textus
+  module Step
+    class MachineIntakeFetch < Fetch
+      def call(config:, args:, caps:, **)
+        machine = args[:leaf_segments].first or
+          raise "machines intake needs a host leaf, e.g. the 'local' in feeds.machines.local"
+        spec = (config["machines"] || {}).fetch(machine) { raise "unknown machine: #{machine}" }
+        unless (spec["via"] || "local").to_s == "local"
+          raise "machine #{machine}: only `via: local` is scaffolded — see " \
+                "docs/cookbook/environment-scan.md for the SSH (remote) fan-out"
+        end
 
-    sh    = ->(cmd) { `#{cmd}`.strip }                      # local shell-out, no network
-    ver   = ->(cmd) { o = `#{cmd} 2>/dev/null`.strip; o.empty? ? nil : o } # nil if tool absent
-    count = ->(cmd) { n = `#{cmd} 2>/dev/null`.strip.lines.size; n.zero? ? nil : n }
-    { content: {
-      # git_* describe THIS repo on the control host — only meaningful for `local`.
-      "git_head"       => sh.call("git rev-parse --short HEAD 2>/dev/null"),
-      "git_branch"     => sh.call("git rev-parse --abbrev-ref HEAD 2>/dev/null"),
-      "git_dirty"      => !sh.call("git status --porcelain 2>/dev/null").empty?,
-      "repo_root"      => sh.call("git rev-parse --show-toplevel 2>/dev/null"),
-      "captured_at"    => Time.now.utc.iso8601,
-      "os"             => RbConfig::CONFIG["host_os"],
-      "arch"           => RbConfig::CONFIG["host_cpu"],
-      "ruby_version"   => RUBY_VERSION,
-      "runtimes"       => {                                 # versions only; nil when not installed
-        "node"   => ver.call("node --version"),
-        "python" => ver.call("python3 --version"),
-        "go"     => ver.call("go version"),
-      },
-      "packages"       => {                                 # COUNTS only — never the list (size/secrets)
-        "brew" => count.call("brew list --formula"),        # ~1-3s on macOS; runs only on fetch, amortized by the ttl rule
-        "apt"  => count.call("dpkg-query -f '.\n' -W"),
-      },
-      "textus_version" => Textus::VERSION,
-      "protocol"       => Textus::PROTOCOL,
-    } }
+        sh    = ->(cmd) { `#{cmd}`.strip }                      # local shell-out, no network
+        ver   = ->(cmd) { o = `#{cmd} 2>/dev/null`.strip; o.empty? ? nil : o } # nil if tool absent
+        count = ->(cmd) { n = `#{cmd} 2>/dev/null`.strip.lines.size; n.zero? ? nil : n }
+        { content: {
+          # git_* describe THIS repo on the control host — only meaningful for `local`.
+          "git_head"       => sh.call("git rev-parse --short HEAD 2>/dev/null"),
+          "git_branch"     => sh.call("git rev-parse --abbrev-ref HEAD 2>/dev/null"),
+          "git_dirty"      => !sh.call("git status --porcelain 2>/dev/null").empty?,
+          "repo_root"      => sh.call("git rev-parse --show-toplevel 2>/dev/null"),
+          "captured_at"    => Time.now.utc.iso8601,
+          "os"             => RbConfig::CONFIG["host_os"],
+          "arch"           => RbConfig::CONFIG["host_cpu"],
+          "ruby_version"   => RUBY_VERSION,
+          "runtimes"       => {                                 # versions only; nil when not installed
+            "node"   => ver.call("node --version"),
+            "python" => ver.call("python3 --version"),
+            "go"     => ver.call("go version"),
+          },
+          "packages"       => {                                 # COUNTS only — never the list (size/secrets)
+            "brew" => count.call("brew list --formula"),        # ~1-3s on macOS; runs only on fetch, amortized by the ttl rule
+            "apt"  => count.call("dpkg-query -f '.\n' -W"),
+          },
+          "textus_version" => Textus::VERSION,
+          "protocol"       => Textus::PROTOCOL,
+        } }
+      end
+    end
   end
 end

data/lib/textus/init/templates/orientation_reducer.rb

@@ -1,17 +1,21 @@
 # Reducer that reshapes the raw projection rows into the keys the
 # orientation.mustache template references. Without this, the template
 # would only have access to the flat rows list.
-Textus.hook do |reg|
-  reg.on(:transform_rows, :orientation_reducer) do |rows:, **|
-    project_row = rows.find { |r| r["_key"] == "knowledge.project" } || {}
-    runbook_rows = rows.select { |r| r["_key"]&.start_with?("knowledge.runbooks.") }
+module Textus
+  module Step
+    class OrientationTransform < Transform
+      def call(rows:, config:, **)
+        project_row = rows.find { |r| r["_key"] == "knowledge.project" } || {}
+        runbook_rows = rows.select { |r| r["_key"]&.start_with?("knowledge.runbooks.") }
 
-    {
-      "project" => {
-        "name" => project_row["name"],
-        "description" => project_row["description"]
-      },
-      "runbooks" => runbook_rows.map { |r| { "name" => r["name"], "description" => r["description"] } }
-    }
+        {
+          "project" => {
+            "name" => project_row["name"],
+            "description" => project_row["description"]
+          },
+          "runbooks" => runbook_rows.map { |r| { "name" => r["name"], "description" => r["description"] } }
+        }
+      end
+    end
   end
 end