igniter 0.5.0 → 0.5.1

data/packages/igniter-cluster/lib/igniter/cluster/governance/admission_queue.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Igniter
+  module Cluster
+    module Governance
+      # Thread-safe in-memory queue of admission requests awaiting operator approval.
+      #
+      # Requests stay in the queue until:
+      #   - explicitly approved via approve!(request_id)
+      #   - explicitly rejected via reject!(request_id)
+      #   - expired by expire_stale! when their age exceeds max_ttl
+      class AdmissionQueue
+        def initialize
+          @pending = {}
+          @mutex   = Mutex.new
+        end
+
+        # Enqueue a request. Re-enqueuing the same request_id is idempotent.
+        #
+        # @param request [AdmissionRequest]
+        # @return [AdmissionRequest]
+        def enqueue(request)
+          @mutex.synchronize { @pending[request.request_id] = request }
+          request
+        end
+
+        # All currently pending requests (snapshot).
+        #
+        # @return [Array<AdmissionRequest>]
+        def pending
+          @mutex.synchronize { @pending.values.dup }
+        end
+
+        # Retrieve a specific pending request by id, or nil.
+        #
+        # @param request_id [String]
+        # @return [AdmissionRequest, nil]
+        def find(request_id)
+          @mutex.synchronize { @pending[request_id.to_s] }
+        end
+
+        # Remove and return the request with the given id (approve or reject path).
+        #
+        # @param request_id [String]
+        # @return [AdmissionRequest, nil]
+        def dequeue(request_id)
+          @mutex.synchronize { @pending.delete(request_id.to_s) }
+        end
+
+        # Remove all requests older than ttl_seconds from now.
+        #
+        # @param ttl_seconds [Integer]
+        # @param now         [Time]
+        # @return [Array<AdmissionRequest>]  the expired requests
+        def expire_stale!(ttl_seconds, now: Time.now.utc)
+          cutoff = now - ttl_seconds
+          expired = []
+          @mutex.synchronize do
+            @pending.reject! do |_id, req|
+              ts = Time.parse(req.requested_at) rescue nil
+              next false unless ts
+              next false if ts >= cutoff
+
+              expired << req
+              true
+            end
+          end
+          expired
+        end
+
+        def size
+          @mutex.synchronize { @pending.size }
+        end
+
+        def empty?
+          size.zero?
+        end
+
+        def clear!
+          @mutex.synchronize { @pending.clear }
+          self
+        end
+      end
+    end
+  end
+end

data/packages/igniter-cluster/lib/igniter/cluster/governance/admission_request.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "digest"
+require "securerandom"
+require "time"
+
+module Igniter
+  module Cluster
+    module Governance
+      # A formal peer admission request submitted to the cluster.
+      #
+      # Immutable — created by the requesting peer (or operator) and submitted
+      # to AdmissionWorkflow for policy evaluation.
+      AdmissionRequest = ::Data.define(
+        :request_id,
+        :peer_name,
+        :node_id,
+        :public_key,
+        :url,
+        :capabilities,
+        :justification,
+        :requested_at
+      ) do
+        def self.build(peer_name:, node_id:, public_key:, url: nil, capabilities: [], justification: nil, requested_at: Time.now.utc.iso8601)
+          new(
+            request_id:    SecureRandom.uuid,
+            peer_name:     peer_name.to_s,
+            node_id:       node_id.to_s,
+            public_key:    public_key.to_s,
+            url:           url.to_s,
+            capabilities:  Array(capabilities).map(&:to_sym).freeze,
+            justification: justification&.to_s,
+            requested_at:  requested_at.to_s
+          )
+        end
+
+        # 12-hex fingerprint derived from the public key (matches TrustStore fingerprint convention).
+        def fingerprint
+          Digest::SHA256.hexdigest(public_key)[0, 24]
+        end
+
+        def routable?
+          !url.to_s.empty?
+        end
+
+        def to_h
+          {
+            request_id:   request_id,
+            peer_name:    peer_name,
+            node_id:      node_id,
+            public_key:   public_key,
+            url:          url,
+            capabilities: capabilities,
+            justification: justification,
+            requested_at: requested_at,
+            fingerprint:  fingerprint
+          }
+        end
+      end
+    end
+  end
+end

data/packages/igniter-cluster/lib/igniter/cluster/governance/admission_workflow.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module Governance
+      # Orchestrates the full peer admission lifecycle:
+      #
+      #   1. Accept an AdmissionRequest
+      #   2. Evaluate it against AdmissionPolicy + TrustStore
+      #   3. Record the outcome in the Governance Trail
+      #   4. Update the TrustStore on admission
+      #   5. Auto-register the peer in PeerRegistry when url is present
+      #   6. Return a typed AdmissionDecision
+      #
+      # Outcomes recorded in the governance trail:
+      #   :admission_requested     — every inbound request
+      #   :admission_admitted      — auto-admitted by policy (known key or open policy)
+      #   :admission_pending       — enqueued, awaiting operator approval
+      #   :admission_approved      — operator approved a pending request
+      #   :admission_rejected      — rejected by policy or operator
+      #   :admission_expired       — pending request timed out
+      #
+      # Usage:
+      #   workflow = AdmissionWorkflow.new(config: Igniter::Cluster::Mesh.config)
+      #   decision = workflow.request_admission(peer_name: "node-b", node_id: "b", public_key: pem)
+      #   decision.pending_approval?  # => true
+      #   workflow.approve_pending!(decision.request.request_id)  # => AdmissionDecision(:admitted)
+      class AdmissionWorkflow
+        def initialize(config:)
+          @config = config
+        end
+
+        # Submit a new admission request and return the immediate decision.
+        #
+        # @param peer_name    [String]
+        # @param node_id      [String]
+        # @param public_key   [String]  PEM-encoded public key
+        # @param capabilities [Array<Symbol>]
+        # @param justification [String, nil]
+        # @return [AdmissionDecision]
+        def request_admission(peer_name:, node_id:, public_key:, url: nil, capabilities: [], justification: nil)
+          request = AdmissionRequest.build(
+            peer_name:     peer_name,
+            node_id:       node_id,
+            public_key:    public_key,
+            url:           url,
+            capabilities:  capabilities,
+            justification: justification
+          )
+
+          trail_record(:admission_requested, request: request)
+
+          outcome = policy.evaluate(request, trust_store)
+          decision = AdmissionDecision.build(request: request, outcome: outcome,
+                                             rationale: rationale_for(outcome, request))
+
+          case outcome
+          when :admitted
+            admit_to_trust_store!(request)
+            register_in_peer_registry!(request)
+            trail_record(:admission_admitted, request: request)
+          when :pending_approval
+            queue.enqueue(request)
+            trail_record(:admission_pending, request: request)
+          when :rejected
+            trail_record(:admission_rejected, request: request,
+                         extra: { reason: :forbidden_capability })
+          when :already_trusted
+            # no trail entry — idempotent
+          end
+
+          decision
+        end
+
+        # Approve a pending request by its request_id.
+        #
+        # @param request_id [String]
+        # @return [AdmissionDecision]  :admitted or :not_found
+        def approve_pending!(request_id)
+          request = queue.dequeue(request_id.to_s)
+          unless request
+            return AdmissionDecision.build(
+              request:   stub_request(request_id),
+              outcome:   :rejected,
+              rationale: "request not found in pending queue"
+            )
+          end
+
+          admit_to_trust_store!(request)
+          register_in_peer_registry!(request)
+          trail_record(:admission_approved, request: request)
+          AdmissionDecision.build(request: request, outcome: :admitted,
+                                  rationale: "approved by operator")
+        end
+
+        # Reject a pending request by its request_id.
+        #
+        # @param request_id [String]
+        # @param reason     [String, nil]
+        # @return [AdmissionDecision]
+        def reject_pending!(request_id, reason: nil)
+          request = queue.dequeue(request_id.to_s)
+          unless request
+            return AdmissionDecision.build(
+              request:   stub_request(request_id),
+              outcome:   :rejected,
+              rationale: "request not found in pending queue"
+            )
+          end
+
+          trail_record(:admission_rejected, request: request,
+                       extra: { reason: reason || :operator_rejected })
+          AdmissionDecision.build(request: request, outcome: :rejected,
+                                  rationale: reason || "rejected by operator")
+        end
+
+        # Approve all currently pending requests.
+        #
+        # @return [Array<AdmissionDecision>]
+        def approve_all_pending!
+          queue.pending.map { |req| approve_pending!(req.request_id) }
+        end
+
+        # Expire pending requests older than the policy TTL.
+        #
+        # @param now [Time]
+        # @return [Array<AdmissionDecision>]
+        def expire_stale!(now: Time.now.utc)
+          expired = queue.expire_stale!(policy.max_pending_ttl, now: now)
+          expired.map do |req|
+            trail_record(:admission_expired, request: req)
+            AdmissionDecision.build(request: req, outcome: :rejected,
+                                    rationale: "pending request expired (ttl=#{policy.max_pending_ttl}s)")
+          end
+        end
+
+        # All currently pending requests.
+        #
+        # @return [Array<AdmissionRequest>]
+        def pending_requests
+          queue.pending
+        end
+
+        private
+
+        def policy
+          @config.admission_policy ||= AdmissionPolicy.new
+        end
+
+        def queue
+          @config.admission_queue ||= AdmissionQueue.new
+        end
+
+        def trust_store
+          @config.trust_store
+        end
+
+        def admit_to_trust_store!(request)
+          trust_store.add(
+            request.node_id,
+            public_key: request.public_key,
+            label:      request.peer_name
+          )
+        end
+
+        def register_in_peer_registry!(request)
+          return unless request.routable?
+
+          peer = Igniter::Cluster::Mesh::Peer.new(
+            name:         request.peer_name,
+            url:          request.url,
+            capabilities: request.capabilities,
+            tags:         [],
+            metadata:     {
+              mesh_trust:    { status: "trusted", trusted: true },
+              mesh_identity: { node_id: request.node_id, fingerprint: request.fingerprint }
+            }
+          )
+          @config.peer_registry.register(peer)
+        end
+
+        def trail_record(type, request:, extra: {})
+          @config.governance_trail&.record(
+            type,
+            source:  :admission_workflow,
+            payload: {
+              request_id:  request.request_id,
+              peer_name:   request.peer_name,
+              node_id:     request.node_id,
+              fingerprint: request.fingerprint,
+              capabilities: request.capabilities
+            }.merge(extra).compact
+          )
+        end
+
+        def rationale_for(outcome, request)
+          case outcome
+          when :admitted        then "auto-admitted by policy (known key)"
+          when :pending_approval then "no matching known key — queued for approval"
+          when :rejected        then "request contains forbidden capability"
+          when :already_trusted then "node_id already in trust store"
+          end
+        end
+
+        def stub_request(request_id)
+          AdmissionRequest.new(
+            request_id: request_id.to_s, peer_name: "unknown", node_id: "unknown",
+            public_key: "", url: "", capabilities: [], justification: nil, requested_at: Time.now.utc.iso8601
+          )
+        end
+      end
+    end
+  end
+end

data/packages/igniter-cluster/lib/igniter/cluster/governance/checkpoint.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "openssl"
+require "time"
+
+module Igniter
+  module Cluster
+    module Governance
+      class Checkpoint
+        attr_reader :peer_name, :node_id, :algorithm, :public_key, :crest,
+                    :checkpointed_at, :signature, :previous_digest
+
+        def self.build(identity:, peer_name:, trail:, limit: 10, checkpointed_at: Time.now.utc.iso8601, previous: nil)
+          crest = trail.snapshot(limit: limit)
+          payload = {
+            peer_name: peer_name.to_s,
+            node_id: identity.node_id,
+            algorithm: identity.algorithm,
+            public_key: identity.public_key_pem,
+            crest: crest_payload(crest),
+            checkpointed_at: checkpointed_at.to_s
+          }
+          payload[:previous_digest] = previous.crest_digest if previous
+
+          new(payload.merge(signature: identity.sign(payload)))
+        end
+
+        def self.from_h(hash)
+          new(hash)
+        end
+
+        def self.crest_payload(crest)
+          normalized = symbolize_keys(crest || {})
+          {
+            total: normalized[:total].to_i,
+            latest_type: normalized[:latest_type]&.to_sym,
+            latest_at: normalized[:latest_at],
+            by_type: symbolize_keys(normalized[:by_type] || {}),
+            persistence: symbolize_keys(normalized[:persistence] || {}),
+            events: Array(normalized[:events]).map { |event| normalize_event(event) }
+          }
+        end
+
+        def initialize(hash)
+          source = self.class.send(:symbolize_keys, hash || {})
+          @peer_name = source[:peer_name].to_s.freeze
+          @node_id = source[:node_id].to_s.freeze
+          @algorithm = source[:algorithm].to_s.freeze
+          @public_key = source[:public_key].to_s.freeze
+          @crest = self.class.crest_payload(source[:crest]).freeze
+          @checkpointed_at = source[:checkpointed_at].to_s.freeze
+          @signature = source[:signature].to_s.freeze
+          @previous_digest = source[:previous_digest]&.to_s&.freeze
+          freeze
+        end
+
+        def payload
+          base = {
+            peer_name: peer_name,
+            node_id: node_id,
+            algorithm: algorithm,
+            public_key: public_key,
+            crest: crest,
+            checkpointed_at: checkpointed_at
+          }
+          base[:previous_digest] = previous_digest if previous_digest
+          base
+        end
+
+        def chained?
+          !previous_digest.nil?
+        end
+
+        def verify_signature
+          return false if public_key.empty? || signature.empty?
+
+          key = OpenSSL::PKey.read(public_key)
+          key.verify(OpenSSL::Digest::SHA256.new, Base64.strict_decode64(signature), canonical_json(payload))
+        rescue OpenSSL::PKey::PKeyError, ArgumentError
+          false
+        end
+
+        def fingerprint
+          return nil if public_key.empty?
+
+          OpenSSL::Digest::SHA256.hexdigest(OpenSSL::PKey.read(public_key).to_der)[0, 24]
+        rescue OpenSSL::PKey::PKeyError
+          nil
+        end
+
+        def crest_digest
+          OpenSSL::Digest::SHA256.hexdigest(canonical_json(crest))[0, 24]
+        end
+
+        def to_h
+          payload.merge(signature: signature)
+        end
+
+        private
+
+        def canonical_json(value)
+          JSON.generate(deep_sort(value))
+        end
+
+        def deep_sort(value)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, nested), memo|
+              memo[key.to_s] = deep_sort(nested)
+            end.sort.to_h
+          when Array
+            value.map { |item| deep_sort(item) }
+          when Symbol
+            value.to_s
+          else
+            value
+          end
+        end
+
+        class << self
+          private
+
+          def symbolize_keys(hash)
+            hash.each_with_object({}) do |(key, value), memo|
+              memo[key.to_sym] = value
+            end
+          end
+
+          def normalize_event(event)
+            source = symbolize_keys(event || {})
+            source[:type] = source[:type]&.to_sym
+            source[:source] = source[:source]&.to_sym
+            source
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-cluster/lib/igniter/cluster/governance/compaction_record.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Cluster
+    module Governance
+      # Typed result of Trail#compact!.
+      #
+      # Describes what happened during a compaction: how many events were
+      # removed, how many were kept, and the signed Checkpoint built over
+      # the crest at compaction time (when an identity was provided).
+      CompactionRecord = ::Data.define(:checkpoint, :removed_events, :kept_events, :checkpoint_digest) do
+        # True when events were actually removed.
+        def compacted?
+          removed_events > 0
+        end
+
+        # True when a signed Checkpoint was built alongside the compaction.
+        def signed?
+          !checkpoint.nil?
+        end
+
+        def to_h
+          {
+            compacted:         compacted?,
+            removed_events:    removed_events,
+            kept_events:       kept_events,
+            checkpoint_digest: checkpoint_digest
+          }
+        end
+      end
+    end
+  end
+end

data/packages/igniter-cluster/lib/igniter/cluster/governance/stores/checkpoint_store.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Igniter
+  module Cluster
+    module Governance
+      module Stores
+        # File-backed store for a single signed Governance::Checkpoint.
+        #
+        # Saves the latest checkpoint as JSON. On load, deserializes and
+        # optionally verifies the RSA/ECDSA signature before returning.
+        #
+        # Typical usage:
+        #   store  = CheckpointStore.new(path: "var/governance/checkpoint.json")
+        #   record = Mesh.compact_governance!(identity: identity, peer_name: "node-a")
+        #   store.save(record.checkpoint)
+        #
+        #   # On restart:
+        #   cp = store.load_verified   # nil if missing or tampered
+        class CheckpointStore
+          attr_reader :path
+
+          def initialize(path:)
+            @path = path.to_s
+            FileUtils.mkdir_p(File.dirname(@path))
+          end
+
+          # Persist a Checkpoint to disk (overwrites any previous checkpoint).
+          #
+          # @param checkpoint [Checkpoint]
+          # @return [self]
+          def save(checkpoint)
+            File.write(@path, JSON.generate(checkpoint.to_h))
+            self
+          end
+
+          # Load the most recently saved Checkpoint, or nil if none exists.
+          #
+          # @return [Checkpoint, nil]
+          def load
+            return nil unless File.exist?(@path)
+
+            Checkpoint.from_h(deep_symbolize(JSON.parse(File.read(@path))))
+          rescue JSON::ParserError
+            nil
+          end
+
+          # Load and verify the Checkpoint's signature.
+          # Returns nil if the file is missing, malformed, or the signature is invalid.
+          #
+          # @return [Checkpoint, nil]
+          def load_verified
+            cp = load
+            return nil unless cp&.verify_signature
+
+            cp
+          end
+
+          # Remove the persisted checkpoint.
+          #
+          # @return [self]
+          def clear!
+            FileUtils.rm_f(@path)
+            self
+          end
+
+          def exists?
+            File.exist?(@path)
+          end
+
+          private
+
+          def deep_symbolize(value)
+            case value
+            when Hash
+              value.each_with_object({}) { |(k, v), h| h[k.to_sym] = deep_symbolize(v) }
+            when Array
+              value.map { |v| deep_symbolize(v) }
+            else
+              value
+            end
+          end
+        end
+      end
+    end
+  end
+end