igniter 0.5.1 → 0.5.2

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

@@ -1,88 +0,0 @@
-# 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

@@ -1,62 +0,0 @@
-# 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

@@ -1,214 +0,0 @@
-# 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

@@ -1,141 +0,0 @@
-# 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

@@ -1,33 +0,0 @@
-# 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

@@ -1,89 +0,0 @@
-# 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