mt-wall 0.1.0

data/lib/mt/wall/configuration.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Mt
+  module Wall
+    # Root aggregate of a firewall configuration: the in-memory desired
+    # model produced by the DSL and consumed by the Compiler. Objects and
+    # groups are keyed by name (names are unique within a configuration);
+    # rules and global policies are ordered.
+    #
+    # GROUP MEMBERSHIP is single-sourced here. Membership may be declared
+    # group-side (`group "x" { member "y" }`) OR host-side (`member_of` /
+    # trailing positional args on `host`); both fold into the SAME group. A
+    # group referenced only from the host side is created on demand
+    # (auto-create is host-side ONLY — groups referenced solely by
+    # rules/src/dst are resolved/validated later by the Compiler). Hosts and
+    # groups share one name space, so a host and a group may not share a name.
+    class Configuration
+      # Names that may NOT be used for a host or group because they carry a
+      # reserved meaning elsewhere in the DSL. "any" is the match-all
+      # source/destination (see Compiler::ANY_REFERENCE); allowing a host/group
+      # to shadow it would make `rule "any"` / `to "any"` / `src: "any"`
+      # ambiguous, so declaring one fails fast.
+      RESERVED_NAMES = %w[any].freeze
+
+      attr_reader :objects, :services, :rules, :devices, :global_policies
+
+      def initialize
+        @objects = {}         # name (String) => Model::AddressObject
+        @services = {}        # name (String) => Model::Service
+        @rules = []           # Array<Model::Rule>
+        @devices = {}         # name (String) => Model::Device
+        @global_policies = [] # Array<Model::Policy>
+
+        @group_members = {}   # name (String) => Array<String> (ordered, unique)
+        @group_comments = {}  # name (String) => String (comment)
+        @declared_groups = {} # name (String) => true (explicit `group` verb)
+      end
+
+      # Materialize the accumulated group membership (group-side + host-side)
+      # into immutable Model::Group value objects keyed by name.
+      # @return [Hash{String => Model::Group}]
+      def groups
+        @group_members.each_with_object({}) do |(name, members), result|
+          result[name] = Model::Group.new(name: name, members: members, comment: @group_comments[name])
+        end
+      end
+
+      # Record a host (named address object).
+      # @return [void]
+      def add_object(object)
+        name = object.name
+        assert_not_reserved!(name)
+        raise ConfigurationError, "duplicate host #{name.inspect}" if @objects.key?(name)
+
+        assert_no_name_clash!(name)
+        @objects[name] = object
+      end
+
+      # Record an explicit group declaration (group-side membership). Merges
+      # with any host-side membership already folded into the same group.
+      # @return [void]
+      def declare_group(name, members, comment = nil)
+        assert_not_reserved!(name)
+        raise ConfigurationError, "name #{name.inspect} is used by both a host and a group" if @objects.key?(name)
+
+        @declared_groups[name] = true
+        @group_comments[name] = comment if comment
+        add_members(name, members)
+      end
+
+      # Fold a host into a group from the host side, auto-creating the group's
+      # membership bucket on demand.
+      # @return [void]
+      def add_membership(host_name, group_name)
+        assert_not_reserved!(group_name)
+        add_members(group_name, [host_name])
+      end
+
+      # @return [void]
+      def add_service(service)
+        raise ConfigurationError, "duplicate service #{service.name.inspect}" if @services.key?(service.name)
+
+        @services[service.name] = service
+      end
+
+      # @return [void]
+      def add_rule(rule)
+        @rules << rule
+      end
+
+      # @return [void]
+      def add_global_policy(policy)
+        @global_policies << policy
+      end
+
+      # @return [void]
+      def add_device(device)
+        raise ConfigurationError, "duplicate device #{device.name.inspect}" if @devices.key?(device.name)
+
+        @devices[device.name] = device
+      end
+
+      private
+
+      def assert_not_reserved!(name)
+        return unless RESERVED_NAMES.include?(name)
+
+        raise ConfigurationError, "#{name.inspect} is a reserved name"
+      end
+
+      def assert_no_name_clash!(name)
+        return unless @declared_groups.key?(name)
+
+        raise ConfigurationError, "name #{name.inspect} is used by both a host and a group"
+      end
+
+      def add_members(name, members)
+        bucket = (@group_members[name] ||= [])
+        members.each { |member| bucket << member unless bucket.include?(member) }
+      end
+    end
+  end
+end

data/lib/mt/wall/desired_state.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module Mt
+  module Wall
+    # A normalized set of RouterOS resources, keyed by resource path, e.g.:
+    #
+    #   {
+    #     "/ip/firewall/address-list" => [{ list: "web", address: "10.0.0.5" }, ...],
+    #     "/ip/firewall/filter"       => [{ chain: "forward", action: "accept", ... }, ...]
+    #   }
+    #
+    # Both the compiled DESIRED state (from the Compiler) and the fetched
+    # CURRENT state (from a Transport) use this exact shape, so Plan.diff can
+    # compare them path-by-path without knowing about transports or the DSL.
+    #
+    # OWNERSHIP IS PER-TABLE, NOT UNIFORM:
+    #   * FILTER + NAT tables (/ip/firewall/filter, /ipv6/firewall/filter,
+    #     /ip/firewall/nat) are owned WHOLESALE — apply replaces each table
+    #     entirely, including RouterOS default-config rows.
+    #   * ADDRESS-LIST tables (/ip/firewall/address-list,
+    #     /ipv6/firewall/address-list) are owned ONLY for the LIST NAMES the
+    #     Compiler emits from hosts/groups (see Compiler.managed_list_names).
+    #     Foreign/static lists (operator- or script-maintained, not emitted by
+    #     mt-wall) are NEVER touched or deleted. The diff for address-lists is
+    #     scoped to managed names and keyed by the NATURAL KEY `(list, address)`
+    #     — not the device `.id`.
+    # NAT is IPv4-only in v1 — there is no /ipv6/firewall/nat key. The slash-
+    # delimited path is also the REST URL suffix the transport maps to
+    # (`/rest/ip/firewall/filter`, `/rest/ipv6/firewall/filter`, ...).
+    #
+    # IDENTITY & DIFF CONTRACT (see Plan.diff): filter/nat rows are matched
+    # desired<->current by the `(tag, ordinal)` key built from their content-only
+    # `mt-wall:<stable-hash>` identity tag (in `comment`), NEVER by the opaque
+    # device `.id`; address-list rows match by `(list, address)`. Before
+    # diffing, BOTH sides must be normalized: RouterOS returns booleans/numbers
+    # as STRINGS ("true"/"yes"/"443"), so values are coerced consistently on both
+    # sides; and rows flagged `dynamic` (RouterOS-generated, not user-managed)
+    # are EXCLUDED from the current state so they are never diffed or deleted.
+    #
+    # KEY CONVENTION: rows use Symbol keys in Ruby-idiomatic underscore form
+    # (`:src_address_list`, `:connection_state`, `:dst_port`). A transport is
+    # responsible for mapping those to/from the RouterOS hyphenated REST keys
+    # (`src-address-list`, ...) before handing rows to {.from_current}, so both
+    # sides of the diff share one shape.
+    class DesiredState
+      # Managed IPv4 table paths.
+      IPV4_PATHS = [
+        "/ip/firewall/address-list",
+        "/ip/firewall/filter",
+        "/ip/firewall/nat"
+      ].freeze
+
+      # Managed IPv6 table paths (no NAT in v1).
+      IPV6_PATHS = [
+        "/ipv6/firewall/address-list",
+        "/ipv6/firewall/filter"
+      ].freeze
+
+      # Every path mt-wall reads/owns; the default set Transport#fetch reads.
+      MANAGED_PATHS = (IPV4_PATHS + IPV6_PATHS).freeze
+
+      # Tables owned WHOLESALE (apply replaces them in full). Address-list paths
+      # are deliberately EXCLUDED — they are managed-name-scoped, not wholesale.
+      FULL_TABLE_PATHS = [
+        "/ip/firewall/filter",
+        "/ip/firewall/nat",
+        "/ipv6/firewall/filter"
+      ].freeze
+
+      # Address-list paths owned only for the Compiler-emitted list names; rows
+      # diff by the natural key `(list, address)`.
+      ADDRESS_LIST_PATHS = [
+        "/ip/firewall/address-list",
+        "/ipv6/firewall/address-list"
+      ].freeze
+
+      attr_reader :resources
+
+      def initialize(resources = {})
+        @resources = {}
+        resources.each do |path, rows|
+          Array(rows).each { |row| add(path, row) }
+        end
+      end
+
+      # Append a row to a path, normalizing its values so the desired and
+      # current sides compare equal.
+      # @return [self]
+      def add(path, row)
+        (@resources[path] ||= []) << self.class.normalize_address_list(path, self.class.normalize_row(row))
+        self
+      end
+
+      # @param path [String] RouterOS resource path
+      # @return [Array<Hash>] entries for that path (empty if none)
+      def [](path)
+        @resources.fetch(path, [])
+      end
+
+      # @return [Array<String>] paths that carry at least one row
+      def paths
+        @resources.keys
+      end
+
+      def ==(other)
+        other.is_a?(DesiredState) && resources == other.resources
+      end
+      alias eql? ==
+
+      def hash
+        resources.hash
+      end
+
+      # Coerce a single value to its normalized String form (or nil to drop the
+      # key). RouterOS REST renders booleans/numbers as strings, so the desired
+      # side is coerced the same way to stay diffable.
+      # @return [String, nil]
+      def self.normalize_value(value)
+        case value
+        when nil   then nil
+        when Range then "#{value.first}-#{value.last}"
+        when Array
+          value.empty? ? nil : value.map { |element| normalize_value(element) }.compact.join(",")
+        else value.to_s # String/Symbol/Integer/true/false all render correctly
+        end
+      end
+
+      # Canonicalize the `:address` of an address-list row so the desired and
+      # current sides compare equal regardless of which form RouterOS returns
+      # (it stores v4 hosts bare but v6 hosts as `/128`). Applied IDENTICALLY on
+      # both sides via {#add}, so the chosen form only has to be internally
+      # consistent. Non-address-list paths and rows without an `:address` are
+      # returned unchanged.
+      # @return [Hash]
+      def self.normalize_address_list(path, row)
+        return row unless ADDRESS_LIST_PATHS.include?(path) && row.key?(:address)
+
+        row.merge(address: canonical_address(row[:address]))
+      end
+
+      # Canonical address form: a single host is rendered BARE (redundant `/32`
+      # or `/128` stripped — this is what RouterOS returns for v4 hosts, so both
+      # sides agree); a CIDR subnet is rendered as its normalized `network/prefix`
+      # (IPAddr masks host bits and compresses IPv6). Values IPAddr cannot parse
+      # — RANGES like `10.0.0.1-10.0.0.10` or any other non-IP form — are left
+      # UNTOUCHED so they are never mangled or made to raise.
+      # @return [String]
+      def self.canonical_address(value)
+        ip = IPAddr.new(value)
+        host_prefix = ip.ipv4? ? 32 : 128
+        ip.prefix == host_prefix ? ip.to_s : "#{ip}/#{ip.prefix}"
+      rescue IPAddr::Error
+        value
+      end
+
+      # Normalize every value in a row to its String form, dropping keys whose
+      # value normalizes to nil (absent / empty).
+      # @return [Hash]
+      def self.normalize_row(row)
+        row.each_with_object({}) do |(key, value), out|
+          normalized = normalize_value(value)
+          out[key] = normalized unless normalized.nil?
+        end
+      end
+
+      # Build a CURRENT-state DesiredState from a transport's raw resource hash:
+      # values are string-coerced, `dynamic` rows are dropped (RouterOS-generated,
+      # never user-managed) and address-list rows are scoped to the managed list
+      # names so foreign/static lists are never diffed or deleted.
+      # @param raw_resources [Hash{String => Array<Hash>}]
+      # @param managed_list_names [Array<String>]
+      # @return [DesiredState]
+      def self.from_current(raw_resources, managed_list_names: [])
+        managed = managed_list_names.map(&:to_s)
+        raw_resources.each_with_object(new) do |(path, rows), state|
+          Array(rows).each { |row| ingest_current(state, path, row, managed) }
+        end
+      end
+
+      # @return [void]
+      def self.ingest_current(state, path, row, managed)
+        return if dynamic?(row)
+
+        normalized = normalize_row(row)
+        return if ADDRESS_LIST_PATHS.include?(path) && !managed.include?(normalized[:list])
+
+        state.add(path, normalized)
+      end
+      private_class_method :ingest_current
+
+      # @return [Boolean] whether a raw row is RouterOS-generated (dynamic).
+      def self.dynamic?(row)
+        value = row[:dynamic] || row["dynamic"]
+        value == true || %w[true yes 1].include?(value.to_s)
+      end
+    end
+  end
+end

data/lib/mt/wall/dsl/chain_builder.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Mt
+  module Wall
+    module DSL
+      # Block context for a single firewall chain inside a `device` block
+      # (Layer B — the box's own firewall). Opened by `input`/`output`/`forward`.
+      # Each verb appends a Model::FilterRule for this chain.
+      #
+      #   forward do
+      #     allow_established              # helper
+      #     drop_invalid                   # helper
+      #     accept protocol: :icmp         # native core
+      #     accept protocol: :tcp, dst_port: 22, src: "admin"
+      #   end
+      #
+      # Two layers of verbs (per the "core + helpers" design):
+      #   * CORE — accept / drop / reject — one rule with native match keywords:
+      #       state:, protocol:, dst_port:, src_port:, in_interface:,
+      #       out_interface:, in_interface_list:, out_interface_list:, src:, dst:,
+      #       family:, comment:, and the rule-level flags log:, log_prefix:,
+      #       disabled: (see below).
+      #     `in_interface_list:` / `out_interface_list:` REFERENCE an existing
+      #     RouterOS `/interface/list` (WAN/LAN, defined by the operator on the
+      #     box) — mt-wall does not manage `/interface/list` itself in v1.
+      #     `log:`/`log_prefix:` enable RouterOS logging; `disabled:` keeps the
+      #     rule in git but inactive. These are rule ATTRIBUTES, not match
+      #     conditions, so they are excluded from the identity tag (toggling them
+      #     is an in-place :update, never delete+create).
+      #     `src:` / `dst:` reference a Layer-A host/group by name (compiled to
+      #     src-/dst-address-list); referencing an unknown name is a fail-fast
+      #     error at compile time.
+      #     `family:` (:ip4 | :ip6) scopes the rule to ONE address family;
+      #     omitted, the rule applies to BOTH (emitted into the v4 AND the v6
+      #     filter tables). Use it for family-specific rules (e.g. ICMPv6).
+      #   * HELPERS — sugar that expands to one or more core rules for the
+      #     common baseline (allow_established, drop_invalid, ...).
+      #
+      # VALIDATION (fail-fast at the DSL boundary): ports are 1..65535 (ranges
+      # allowed); `protocol:` is checked against an allowlist; interface and
+      # host/group names match `\A[\w.-]+\z`. This neutralizes .rsc / JSON
+      # injection through match values.
+      class ChainBuilder
+        # @param chain [Symbol] :input, :output or :forward
+        def initialize(chain)
+          @chain = chain
+          @rules = []
+        end
+
+        # --- core verbs -----------------------------------------------------
+
+        # @return [void]
+        def accept(**match)
+          append(:accept, match)
+        end
+
+        # @return [void]
+        def drop(**match)
+          append(:drop, match)
+        end
+
+        # @return [void]
+        def reject(**match)
+          append(:reject, match)
+        end
+
+        # --- helpers (sugar over the core verbs) ----------------------------
+
+        # accept state: [:established, :related]
+        # @return [void]
+        def allow_established
+          accept(state: %i[established related])
+        end
+
+        # drop state: :invalid
+        # @return [void]
+        def drop_invalid
+          drop(state: :invalid)
+        end
+
+        # The Model::FilterRule list collected for this chain.
+        # @return [Array<Model::FilterRule>]
+        attr_reader :rules
+
+        private
+
+        def append(action, match)
+          match = match.dup
+          family = match.delete(:family)
+          comment = match.delete(:comment)
+          flags = extract_flags!(match)
+
+          @rules << Model::FilterRule.new(
+            chain: @chain, action: action, comment: comment,
+            match: Validators.normalize_match(match, allow_state: true),
+            family: family && Validators.validate_family!(family), **flags
+          )
+        end
+
+        # Pull the rule-level flag keywords out of the match hash and validate
+        # them (they are attributes, not match conditions).
+        def extract_flags!(match)
+          Validators.rule_flags(
+            log: match.delete(:log) || false,
+            log_prefix: match.delete(:log_prefix),
+            disabled: match.delete(:disabled) || false
+          )
+        end
+      end
+    end
+  end
+end

data/lib/mt/wall/dsl/device_builder.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Mt
+  module Wall
+    module DSL
+      # Block context for the `device` verb. Configures the box's OWN firewall
+      # (Layer B), decoupled from the abstract host/group/rule model (Layer A).
+      # The abstract grants are device-agnostic and compiled into this device's
+      # forward chain by the Compiler — they are NOT declared here.
+      #
+      # Verbs:
+      #   * policy <chain>, <action>      — override the global chain default
+      #   * input / output / forward { } — open a ChainBuilder for that chain
+      #     (the box's own input/output rules and the forward baseline, e.g.
+      #     established/related/invalid handling)
+      #   * nat { }                       — open a NatBuilder (the box's
+      #     `/ip firewall nat` table; IPv4-only for v1)
+      #   * management src:, service:, port: — explicitly declare the mgmt
+      #     traffic the safe-chain must protect against lockout (else inferred
+      #     from the transport). REPEATABLE: each call adds another protected
+      #     path; the compiler emits the union of all of them.
+      #
+      #   device "edge-1", host: "10.0.0.1", transport: :rest_api do
+      #     policy :input,   :drop
+      #     policy :forward, :drop
+      #     management src: "admin", service: "ssh"   # optional; inferred if omitted
+      #
+      #     input do
+      #       allow_established
+      #       drop_invalid
+      #       accept protocol: :icmp
+      #       accept protocol: :tcp, dst_port: 22, src: "admin"   # mgmt access
+      #     end
+      #
+      #     forward do
+      #       allow_established
+      #       drop_invalid
+      #       # global Layer-A grants are injected here, then the default policy
+      #     end
+      #
+      #     nat do
+      #       masquerade out_interface: "ether1-wan"
+      #       dst_nat protocol: :tcp, dst_port: 443, in_interface: "ether1-wan",
+      #               to_addresses: "10.0.0.5", to_ports: 8443
+      #     end
+      #   end
+      class DeviceBuilder
+        include PolicyScope
+
+        def initialize(name, host:, transport: :rest_api, **options)
+          @name = name
+          @host = host
+          @transport = transport
+          @options = options
+          @policies = []
+          @filter_rules = []
+          @nat_rules = []
+          @management = []
+        end
+
+        # Open a chain context; collected FilterRules are tagged with the chain.
+        # @yield a ChainBuilder context
+        # @return [void]
+        def input(&block)
+          collect_chain(:input, &block)
+        end
+
+        # @return [void]
+        def output(&block)
+          collect_chain(:output, &block)
+        end
+
+        # @return [void]
+        def forward(&block)
+          collect_chain(:forward, &block)
+        end
+
+        # Open a NatBuilder context; collected NatRules are stored on the device.
+        # @yield a NatBuilder context
+        # @return [void]
+        def nat(&block)
+          builder = NatBuilder.new
+          builder.instance_eval(&block) if block
+          @nat_rules.concat(builder.rules)
+        end
+
+        # Explicitly declare the management traffic the safe-chain must keep
+        # open (INPUT chain only), so an apply can never lock the operator out.
+        # EXPLICIT is PRIMARY; `src` references a Layer-A host/group, `service`
+        # references a Service by name, `port` is a raw port. Stored on
+        # Model::Device#management.
+        #
+        # REPEATABLE: each call ADDS one protected management path; the Compiler
+        # emits the UNION of all of them (so a device can protect, e.g., an SSH
+        # admin AND a REST/CI apply channel from different sources). A second
+        # call no longer overwrites the first.
+        #
+        # This declaration becomes REQUIRED whenever the device locks its input
+        # chain (`policy :input, :drop`): the Compiler FAILS FAST
+        # (ConfigurationError) if NO management path is declared. Transport
+        # inference is only a best-effort BACKSTOP (full mgmt service set —
+        # winbox 8291, ssh 22, api 8728, rest 80/443 — both families) used ONLY
+        # when no explicit management path exists, and is NEVER treated as the
+        # authoritative human mgmt source when the input chain is locked; the
+        # apply-connection source in particular is not authoritative.
+        #
+        #   management src: "admin", service: "ssh"
+        #   management src: "ci",    port: 443        # adds a second path
+        #
+        # @param src     [String, nil]         host/group name -> src-address-list
+        # @param service [String, nil]         Service name (protocol/port)
+        # @param port    [Integer, Array, nil] raw port(s) if no Service is used
+        # @return [void]
+        def management(src: nil, service: nil, port: nil)
+          Validators.validate_name!(src, label: "management src") if src
+          Validators.validate_name!(service, label: "management service") if service
+          Validators.validate_ports!(port) unless port.nil?
+
+          spec = { src: src, service: service, port: port }.compact
+          @management << spec unless spec.empty?
+        end
+
+        # PolicyScope storage hook.
+        # @return [void]
+        def record_policy(policy)
+          @policies << policy
+        end
+
+        # Materialize the collected policies / filter rules / nat rules /
+        # management spec into a Model::Device.
+        # @return [Model::Device]
+        def to_device
+          Model::Device.new(name: Validators.validate_name!(@name, label: "device"),
+                            host: @host, transport: @transport, policies: @policies,
+                            filter_rules: @filter_rules, nat_rules: @nat_rules,
+                            management: @management, options: @options)
+        end
+
+        private
+
+        def collect_chain(chain, &block)
+          builder = ChainBuilder.new(chain)
+          builder.instance_eval(&block) if block
+          @filter_rules.concat(builder.rules)
+        end
+      end
+    end
+  end
+end

data/lib/mt/wall/dsl/group_builder.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Mt
+  module Wall
+    module DSL
+      # Block context for the `group` verb. Declares member hosts and/or other
+      # groups by name. Membership is resolved and flattened later by the
+      # Compiler (RouterOS address-lists are not nestable).
+      #
+      #   group "frontend" do
+      #     member "web"
+      #     member "api"
+      #   end
+      class GroupBuilder
+        def initialize(name, comment: nil)
+          @name = name
+          @comment = comment
+          @members = []
+        end
+
+        # @param name [String] name of a host or another group
+        # @return [void]
+        def member(name)
+          @members << Validators.validate_name!(name, label: "member")
+        end
+
+        # Materialize the collected members into a Model::Group.
+        # @return [Model::Group]
+        def to_group
+          Model::Group.new(name: Validators.validate_name!(@name, label: "group"),
+                           members: @members, comment: @comment)
+        end
+      end
+    end
+  end
+end

data/lib/mt/wall/dsl/host_builder.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Mt
+  module Wall
+    module DSL
+      # Block context for the `host` verb. Collects one or more addresses or
+      # CIDR subnets (and optional group memberships) and produces a
+      # Model::AddressObject.
+      #
+      #   host "web" do
+      #     address "10.0.0.5"
+      #     address "10.0.1.0/24"
+      #     member_of "web-prod", "web-wordpress"
+      #   end
+      #
+      # "host" here means a named address object (an address-list), not
+      # necessarily a single machine: a host may hold several addresses and/or
+      # subnets.
+      #
+      # `member_of` is sugar for declaring membership from the host side. It
+      # does NOT live on the AddressObject: the named host is folded into each
+      # referenced Group's members (membership is single-sourced in
+      # Model::Group). A referenced group that was not declared elsewhere is
+      # created on demand.
+      class HostBuilder
+        def initialize(name, comment: nil)
+          @name = name
+          @comment = comment
+          @addresses = []
+          @memberships = []
+        end
+
+        # @param value [String] an IPv4/IPv6 address or CIDR subnet
+        #   (family is inferred via IPAddr; an unparseable value is a fail-fast
+        #   ConfigurationError)
+        # @return [void]
+        def address(value)
+          @addresses << Validators.validate_address!(value)
+        end
+
+        # Declare that this host belongs to one or more groups (by name).
+        # @param group_names [Array<String>]
+        # @return [void]
+        def member_of(*group_names)
+          group_names.each { |name| @memberships << Validators.validate_group_token!(name) }
+        end
+
+        # Group names this host should be folded into. Read by RootBuilder
+        # after the block runs, to extend each Group's members.
+        # @return [Array<String>]
+        attr_reader :memberships
+
+        # Materialize the collected addresses into a Model::AddressObject.
+        # @return [Model::AddressObject]
+        def to_object
+          raise ConfigurationError, "host #{@name.inspect} has no addresses; declare at least one" if @addresses.empty?
+
+          Model::AddressObject.new(name: Validators.validate_name!(@name, label: "host"),
+                                   addresses: @addresses, comment: @comment)
+        end
+      end
+    end
+  end
+end