ace-lab 0.1.0

data/lib/ace/lab/models/runtime_binding.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Ace
+  module Lab
+    module Models
+      # Immutable runtime binding of an agent or service (spec 8wq.t.1w4).
+      # Carries configured identity facts only — never probes a runtime.
+      # Freshness (active state + exact instance/attestation identity match)
+      # is classified by Atoms::BindingFreshness.
+      class RuntimeBinding
+        KINDS = %w[runtime service].freeze
+
+        attr_reader :kind, :state, :instance_id, :attested_instance_id
+
+        def initialize(kind:, state: nil, instance_id: nil, attested_instance_id: nil)
+          # Defensive frozen copies: these strings feed the freshness facts,
+          # and a mutated shared string could turn a stale binding fresh
+          # despite the frozen model (review round 15, F1)
+          @kind = kind.dup.freeze
+          @state = state && state.dup.freeze
+          @instance_id = instance_id && instance_id.dup.freeze
+          @attested_instance_id = attested_instance_id && attested_instance_id.dup.freeze
+          freeze
+        end
+
+        def self.from_h(hash)
+          new(
+            kind: hash["kind"],
+            state: hash["state"],
+            instance_id: hash["instance_id"],
+            attested_instance_id: hash["attested_instance_id"]
+          )
+        end
+
+        def to_h
+          {
+            "kind" => kind, "state" => state,
+            "instance_id" => instance_id, "attested_instance_id" => attested_instance_id
+          }
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/models/topology_entry.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "runtime_binding"
+
+module Ace
+  module Lab
+    module Models
+      # Immutable stable-ID registry entry (spec 8wq.t.1w4). One of:
+      # project, agent, or service. Stable IDs are canonical; labels are
+      # display values only. Built from schema-normalized configuration.
+      class TopologyEntry
+        KINDS = %w[project agent service].freeze
+
+        attr_reader :kind, :id, :project, :label, :role, :capabilities,
+          :default_for, :endpoint, :binding
+
+        def initialize(kind:, id:, project: nil, label: nil, role: nil,
+          capabilities: [], default_for: [], endpoint: nil, binding: nil)
+          unless KINDS.include?(kind)
+            raise ArgumentError, "unknown entry kind: #{kind}"
+          end
+
+          @kind = kind
+          # Defensive copies: public projections expose these strings, and a
+          # mutated shared string would corrupt the stable-ID/index invariant
+          # or routing facts — element-wise freezing included, since
+          # containers alone leave their string values mutable
+          # (review rounds 15-16, F1)
+          @id = id.dup.freeze
+          @project = project && project.dup.freeze
+          @label = label && label.dup.freeze
+          @role = role && role.dup.freeze
+          @capabilities = capabilities.map { |value| value.dup.freeze }.freeze
+          @default_for = default_for.map { |value| value.dup.freeze }.freeze
+          @endpoint = endpoint && endpoint.transform_values { |value| value.dup.freeze }.freeze
+          @binding = binding
+          freeze
+        end
+
+        def self.project(hash)
+          new(kind: "project", id: hash["id"], label: hash["label"])
+        end
+
+        def self.agent(hash)
+          new(
+            kind: "agent", id: hash["id"], project: hash["project"],
+            label: hash["label"], role: hash["role"],
+            capabilities: hash["capabilities"],
+            binding: Models::RuntimeBinding.from_h(hash["binding"] || {})
+          )
+        end
+
+        def self.service(hash)
+          new(
+            kind: "service", id: hash["id"], project: hash["project"],
+            label: hash["label"], capabilities: hash["capabilities"],
+            default_for: hash["default_for"], endpoint: hash["endpoint"],
+            binding: Models::RuntimeBinding.from_h(hash["binding"] || {})
+          )
+        end
+
+        def project?
+          kind == "project"
+        end
+
+        # Capability check for routing; capabilities are normalized
+        # (stripped, lowercased) at schema validation
+        def capable_of?(capability)
+          capabilities.include?(capability)
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/molecules/caller_authorizer.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "etc"
+
+module Ace
+  module Lab
+    module Molecules
+      # Derives the verified local caller identity and enforces the
+      # project-visibility policy from configured authorization principals
+      # (spec 8wq.t.1w4). Caller identity comes from the local process owner
+      # (username or numeric uid) — never from a CLI flag. An identity with no
+      # matching principal is authorized for nothing.
+      class CallerAuthorizer
+        # Identity strings of the verified local process owner: the passwd
+        # username and the numeric uid, either of which may be configured.
+        def self.local_identity
+          username = begin
+            Etc.getpwuid(Process.uid)&.name
+          rescue
+            nil
+          end
+          matchable_identities(username, Process.uid)
+        end
+
+        # Usernames and numeric-uid grant keys share one namespace in the
+        # grants file. An all-digit username is matchable only via its uid so
+        # it can never collide with a different user's numeric-uid grant
+        # (subject review: separate caller identity principal namespaces).
+        def self.matchable_identities(username, uid)
+          identities = []
+          identities << username if username && username !~ /\A\d+\z/
+          identities << uid.to_s
+          identities.uniq
+        end
+
+        # @param principals [Hash] authorization.principals from normalized config
+        # @param identity [Array<String>, nil] verified caller identities
+        #   (defaults to the local process owner)
+        def initialize(principals: {}, identity: nil)
+          @principals = principals || {}
+          @identity = identity || self.class.local_identity
+        end
+
+        # Union of project IDs visible to the verified caller
+        # @return [Array<String>]
+        def authorized_project_ids
+          @authorized_project_ids ||= @identity.each_with_object([]) do |name, projects|
+            policy = @principals[name]
+            projects.concat(policy["projects"]) if policy.is_a?(Hash)
+          end.uniq
+        end
+
+        # @return [Boolean] true when the caller may see the project; without
+        #   an argument, true when the caller may see anything at all
+        def authorized?(project_id = nil)
+          return authorized_project_ids.any? if project_id.nil?
+
+          authorized_project_ids.include?(project_id)
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/molecules/capability_router.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Ace
+  module Lab
+    module Molecules
+      # Project-local capability routing (spec 8wq.t.1w4). Candidates are
+      # configured capable services of the requested project with fresh
+      # bindings — never services from another project, never stale entries.
+      # Exactly one candidate routes directly; several require exactly one
+      # configured default; otherwise the result is classified ambiguous.
+      class CapabilityRouter
+        # @param index [Molecules::TopologyIndex]
+        # @param authorizer [Molecules::CallerAuthorizer]
+        def initialize(index:, authorizer:)
+          @index = index
+          @authorizer = authorizer
+        end
+
+        def route(project:, capability:)
+          unless @authorizer.authorized?(project)
+            return Models::QueryResult.failure(
+              "unauthorized", "caller is not authorized for project #{project.inspect}", project: project
+            )
+          end
+
+          capability = normalize_capability(capability)
+          candidates = @index.services.select do |service|
+            service.project == project &&
+              service.capable_of?(capability) &&
+              Atoms::BindingFreshness.fresh?(service.binding)
+          end
+
+          if candidates.empty?
+            return Models::QueryResult.failure(
+              "missing",
+              "no available service with capability #{capability.inspect} in project #{project.inspect}",
+              project: project, capability: capability
+            )
+          end
+
+          if candidates.length == 1
+            return Models::QueryResult.ok("entry" => Atoms::PublicProjection.service(candidates.first))
+          end
+
+          # Conflicting defaults are not a preference: exactly one configured
+          # default may win, several classify ambiguous (review R1)
+          defaults = candidates.select { |service| service.default_for.include?(capability) }
+          if defaults.length == 1
+            Models::QueryResult.ok("entry" => Atoms::PublicProjection.service(defaults.first))
+          else
+            Models::QueryResult.failure(
+              "ambiguous",
+              "multiple capable services in project #{project.inspect} for capability #{capability.inspect}: " \
+                "#{candidates.map(&:id).join(", ")}; configure default_for on exactly one to disambiguate",
+              project: project, capability: capability
+            )
+          end
+        end
+
+        private
+
+        # Requested capabilities normalize the same way as configured ones
+        def normalize_capability(capability)
+          capability.to_s.strip.downcase
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/molecules/exact_resolver.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Ace
+  module Lab
+    module Molecules
+      # Exact stable-ID resolution (spec 8wq.t.1w4). Labels never resolve or
+      # disambiguate; only an exact configured ID matches. An entry outside
+      # the caller's authorization resolves exactly like a nonexistent one,
+      # so callers cannot probe private topology by comparing classified
+      # errors (review round 3, F3). A matched, authorized entry with an
+      # unfresh binding is an explicit stale result, never a routeable answer.
+      class ExactResolver
+        # @param index [Molecules::TopologyIndex]
+        # @param authorizer [Molecules::CallerAuthorizer]
+        def initialize(index:, authorizer:)
+          @index = index
+          @authorizer = authorizer
+        end
+
+        def resolve(id)
+          entry = visible_entry(id)
+          return missing(id) if entry.nil?
+
+          unless entry.project? || Atoms::BindingFreshness.fresh?(entry.binding)
+            return Models::QueryResult.failure(
+              "stale",
+              "stable ID #{id.inspect} has a stale runtime binding; a replaced process must re-attest before routing",
+              id: id, project: entry.project
+            )
+          end
+
+          Models::QueryResult.ok("entry" => Atoms::PublicProjection.entry(entry))
+        end
+
+        private
+
+        def visible_entry(id)
+          entry = @index.lookup(id)
+          return nil if entry.nil?
+
+          authorized = if entry.project?
+            @authorizer.authorized?(entry.id)
+          else
+            @authorizer.authorized?(entry.project)
+          end
+
+          authorized ? entry : nil
+        end
+
+        def missing(id)
+          Models::QueryResult.failure("missing", "no topology entry with stable ID #{id.inspect}", id: id)
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/molecules/grant_resolver.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Ace
+  module Lab
+    module Molecules
+      # Resolves authorization grants from the single deployment-controlled
+      # document at a fixed path — never from the configuration cascade and
+      # never from caller-selected locations (review rounds 4-5).
+      #
+      # Trust is established per traversal hop along the ORIGINAL path: every
+      # element — directories, any symlinks, and the file itself — must be
+      # root-owned and not group/world-writable, so a caller-writable
+      # directory cannot redirect the path to attacker-chosen content
+      # (review round 8, F2). The final component is opened O_NOFOLLOW and
+      # re-verified via fstat. Grants are validated structurally only and
+      # intersect with the local topology at query time: the grants file is
+      # machine-global while topology is per-directory (review round 8, F1).
+      # Any failed verification fails closed; no trusted document means
+      # nobody is authorized.
+      class GrantResolver
+        MAX_SYMLINK_HOPS = 8
+
+        class << self
+          # @param documents [Array<Hash>] {path:, document:, defaults:}
+          #   from Ace::Lab.cascade_documents
+          # @param topology [Hash] normalized topology (project IDs)
+          # @param trusted_path [String] fixed deployment grants path
+          # @return [Hash] principals mapping for CallerAuthorizer
+          # @raise [Ace::Lab::InvalidConfigurationError]
+          def resolve(documents:, topology:, trusted_path:)
+            offending = documents.reject { |document| document[:defaults] }
+              .find { |document| document[:document].key?("authorization") }
+            if offending
+              raise Ace::Lab::InvalidConfigurationError,
+                "invalid lab configuration: authorization grants come from the trusted file " \
+                "#{trusted_path}, not the cascade; remove the authorization section from #{offending[:path]}"
+            end
+
+            content = read_verified(trusted_path)
+            return {"principals" => {}} if content.nil?
+
+            parse_grants(content, trusted_path)
+          end
+
+          private
+
+          def verify_error(path)
+            "invalid lab configuration: trusted authorization file #{path} failed the deployment " \
+              "ownership verification or could not be read; failing closed " \
+              "(required: every traversed element root-owned and not group/world-writable)"
+          end
+
+          # Read the grants document only after proving the deployment owns
+          # the storage along the original path. Genuine absence is nil
+          # (nobody authorized); every other filesystem failure — including
+          # races between lstat and open — classifies fail-closed
+          # (review rounds 6-7, F2).
+          # @return [String, nil] file content, or nil when absent
+          def read_verified(path)
+            candidate = begin
+              verified_resolve(path)
+            rescue Ace::Lab::InvalidConfigurationError
+              raise
+            rescue
+              raise Ace::Lab::InvalidConfigurationError, verify_error(path)
+            end
+            return nil if candidate.nil?
+
+            begin
+              io = File.open(candidate, File::RDONLY | File::NOFOLLOW)
+              begin
+                raise Ace::Lab::InvalidConfigurationError, verify_error(path) unless secure_file_stat?(io.stat)
+
+                io.read
+              ensure
+                io.close
+              end
+            rescue Ace::Lab::InvalidConfigurationError
+              raise
+            rescue
+              raise Ace::Lab::InvalidConfigurationError, verify_error(path)
+            end
+          end
+
+          # Walk the ORIGINAL path component by component. Symlinks are
+          # followed only when the link itself is root-owned (a caller-writable
+          # redirect is rejected); symlink permission bits are ignored because
+          # Linux symlinks always report 0777 and cannot be changed
+          # (review round 9, F1). Intermediate directories must be real,
+          # root-owned directories; the opened file is re-verified via fstat.
+          # @return [String, nil] verified file path, or nil when absent
+          def verified_resolve(path)
+            remaining = path.split(File::SEPARATOR).reject(&:empty?)
+            current = File::SEPARATOR
+            hops = 0
+
+            until remaining.empty?
+              component = remaining.shift
+              candidate = (current == File::SEPARATOR) ? "/#{component}" : File.join(current, component)
+              stat = begin
+                File.lstat(candidate)
+              rescue Errno::ENOENT, Errno::ENOTDIR
+                return nil
+              end
+
+              if stat.symlink?
+                hops += 1
+                raise Ace::Lab::InvalidConfigurationError, verify_error(path) if hops > MAX_SYMLINK_HOPS
+                raise Ace::Lab::InvalidConfigurationError, verify_error(path) unless stat.uid.zero?
+
+                target = File.readlink(candidate)
+                target_components = target.split(File::SEPARATOR).reject(&:empty?)
+                remaining = target_components + remaining
+                current = target.start_with?(File::SEPARATOR) ? File::SEPARATOR : current
+                next
+              end
+
+              if remaining.empty?
+                return candidate
+              end
+
+              unless stat.directory? && secure_file_stat?(stat)
+                raise Ace::Lab::InvalidConfigurationError, verify_error(path)
+              end
+
+              current = candidate
+            end
+
+            raise Ace::Lab::InvalidConfigurationError, verify_error(path)
+          end
+
+          def secure_file_stat?(stat)
+            stat.uid.zero? && (stat.mode & 0o022).zero?
+          end
+
+          # Structural validation only: the grants file is machine-global, so
+          # referenced projects may legitimately not exist in the local
+          # directory's topology; such grants simply never match at query
+          # time (review round 8, F1). Messages are value-free.
+          def parse_grants(content, path)
+            document = YAML.safe_load(content, permitted_classes: [Date], aliases: true)
+            unless document.is_a?(Hash)
+              raise Ace::Lab::InvalidConfigurationError,
+                "invalid lab configuration: trusted authorization file #{path} must contain a YAML mapping"
+            end
+
+            principals = document["principals"] || {}
+            unless principals.is_a?(Hash)
+              raise Ace::Lab::InvalidConfigurationError,
+                "invalid lab configuration: trusted authorization file #{path} principals must be a mapping"
+            end
+
+            validated = principals.map do |identity, policy|
+              unless identity.is_a?(String) && !identity.strip.empty?
+                raise Ace::Lab::InvalidConfigurationError,
+                  "invalid lab configuration: trusted authorization file #{path} principal name " \
+                  "must be a non-empty string"
+              end
+              unless policy.is_a?(Hash) && policy["projects"].is_a?(Array) &&
+                  policy["projects"].all? { |project| project.is_a?(String) && !project.strip.empty? }
+                raise Ace::Lab::InvalidConfigurationError,
+                  "invalid lab configuration: trusted authorization file #{path} principal projects " \
+                  "must be an array of non-empty strings"
+              end
+
+              [identity.strip, {"projects" => policy["projects"].map(&:strip).uniq}]
+            end
+
+            {"principals" => validated.to_h}
+          rescue Psych::Exception
+            raise Ace::Lab::InvalidConfigurationError,
+              "invalid lab configuration: trusted authorization file #{path} could not be parsed as YAML"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/molecules/inventory_query.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Ace
+  module Lab
+    module Molecules
+      # Project-scoped inventory queries over a validated TopologyIndex
+      # (spec 8wq.t.1w4). Every result is authorization-filtered: a caller
+      # sees only projects covered by a configured principal, and an
+      # unauthorized project is indistinguishable from any other
+      # unauthorized project (classified error, no metadata).
+      class InventoryQuery
+        # @param index [Molecules::TopologyIndex]
+        # @param authorizer [Molecules::CallerAuthorizer]
+        def initialize(index:, authorizer:)
+          @index = index
+          @authorizer = authorizer
+        end
+
+        # Authorized projects only; a caller with no principals sees nothing
+        def projects
+          return unauthorized_inventory unless @authorizer.authorized?
+
+          visible = @index.projects.select { |project| @authorizer.authorized?(project.id) }
+          Models::QueryResult.ok("projects" => visible.map { |p| Atoms::PublicProjection.project(p) })
+        end
+
+        def agents(project:)
+          return unauthorized_project(project) unless @authorizer.authorized?(project)
+          return missing_project(project) unless project_exists?(project)
+
+          scoped = @index.agents.select { |agent| agent.project == project }
+          Models::QueryResult.ok("agents" => scoped.map { |a| Atoms::PublicProjection.agent(a) })
+        end
+
+        def services(project:)
+          return unauthorized_project(project) unless @authorizer.authorized?(project)
+          return missing_project(project) unless project_exists?(project)
+
+          scoped = @index.services.select { |service| service.project == project }
+          Models::QueryResult.ok("services" => scoped.map { |s| Atoms::PublicProjection.service(s) })
+        end
+
+        private
+
+        # Machine-wide grants may name projects absent from the local
+        # topology; an unknown project is an error, never a valid empty
+        # inventory (review round 17, F1)
+        def project_exists?(project)
+          entry = @index.lookup(project)
+          !entry.nil? && entry.project?
+        end
+
+        def missing_project(project)
+          Models::QueryResult.failure(
+            "missing",
+            "no project #{project.inspect} in the configured topology",
+            project: project
+          )
+        end
+
+        def unauthorized_inventory
+          Models::QueryResult.failure(
+            "unauthorized",
+            "caller has no configured authorization for any lab project"
+          )
+        end
+
+        def unauthorized_project(project)
+          Models::QueryResult.failure(
+            "unauthorized",
+            "caller is not authorized for project #{project.inspect}",
+            project: project
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/molecules/topology_loader.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Ace
+  module Lab
+    module Molecules
+      # Indexed view of validated lab topology (spec 8wq.t.1w4): entries by
+      # globally-unique stable ID plus per-kind collections. Immutable.
+      class TopologyIndex
+        attr_reader :projects, :agents, :services, :by_id
+
+        def initialize(projects:, agents:, services:, by_id:)
+          @projects = projects.freeze
+          @agents = agents.freeze
+          @services = services.freeze
+          @by_id = by_id.freeze
+          freeze
+        end
+
+        def lookup(id)
+          by_id[id]
+        end
+      end
+
+      # Loads ADR-022-resolved lab configuration, validates it through
+      # Atoms::TopologySchema, and builds the immutable TopologyIndex.
+      class TopologyLoader
+        def initialize(config = nil)
+          @config = config
+        end
+
+        # @return [TopologyIndex]
+        # @raise [Ace::Lab::InvalidConfigurationError]
+        def load
+          normalized = Atoms::TopologySchema.normalize!(@config || Ace::Lab.config)
+
+          projects = normalized["topology"]["projects"].map { |h| Models::TopologyEntry.project(h) }
+          agents = normalized["topology"]["agents"].map { |h| Models::TopologyEntry.agent(h) }
+          services = normalized["topology"]["services"].map { |h| Models::TopologyEntry.service(h) }
+
+          by_id = (projects + agents + services).each_with_object({}) do |entry, index|
+            index[entry.id] = entry
+          end
+
+          TopologyIndex.new(projects: projects, agents: agents, services: services, by_id: by_id)
+        end
+      end
+    end
+  end
+end