mt-wall 0.1.0

data/lib/mt/wall/compiler.rb

@@ -0,0 +1,613 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Mt
+  module Wall
+    # Compiles the abstract Configuration into a transport-agnostic
+    # DesiredState of concrete RouterOS resources for one device.
+    #
+    # This is where the domain -> RouterOS mapping happens:
+    #   * objects               -> address-list entries, partitioned BY FAMILY
+    #                              into /ip/firewall/address-list (v4) and
+    #                              /ipv6/firewall/address-list (v6)
+    #   * groups                -> FLATTENED into address-list entries
+    #                              (RouterOS has no nested lists)
+    #   * allow/deny grants      -> filter rules with src-address-list /
+    #                              dst-address-list, emitted PER FAMILY into the
+    #                              v4 and/or v6 filter tables
+    #   * device filter_rules    -> /ip + /ipv6 filter rules (both families
+    #                              unless scoped by `family:`)
+    #   * device nat_rules       -> /ip/firewall/nat rules (IPv4-only, v1).
+    #                              PURELY Layer-B (per-box): NAT is never the
+    #                              target of Layer-A grant injection.
+    #   * global + per-device    -> trailing default rules per chain
+    #     policies
+    #
+    # Group flattening, address de-duplication, family partitioning and
+    # deterministic rule ordering all live here, so the resulting DesiredState
+    # is stable and diffable.
+    #
+    # ── OWNERSHIP & THE SAFE CHAIN ─────────────────────────────────────────
+    # mt-wall owns the ENTIRE filter/nat tables (filter v4 + v6, nat v4): apply
+    # replaces them wholesale, including RouterOS default-config rules. (The
+    # address-list tables are NOT owned wholesale — only the list NAMES the
+    # compiler emits; see DesiredState.) The Compiler is therefore RESPONSIBLE
+    # for emitting a complete, safe chain — and the preamble is FAMILY-SPECIFIC,
+    # NOT one generic "both families" block.
+    #
+    # Per chain the emitted order is: [family-specific essentials] -> [stateful
+    # preamble] -> [mgmt-protection, INPUT chain only] -> [operator/grant rules]
+    # -> [trailing DEFAULT-POLICY rule, LAST].
+    #
+    # See the project CLAUDE.md and Model docs for the full contract; the
+    # implementation below follows it verbatim.
+    class Compiler # rubocop:disable Metrics/ClassLength
+      # Prefix of the machine identity tag embedded in every managed rule's
+      # `comment`. Plan.diff keys on `"#{MANAGED_COMMENT_PREFIX}<hash>"`.
+      MANAGED_COMMENT_PREFIX = "mt-wall:"
+
+      # Separator between the machine identity tag and the operator note inside a
+      # rendered RouterOS `comment`.
+      COMMENT_SEPARATOR = " | "
+
+      # Reserved match-all source/destination. When a grant's source/destination
+      # or a chain rule's `src:`/`dst:` is this name, the compiled filter rule
+      # OMITS the corresponding address-list field (RouterOS treats an absent
+      # list as "match any") and the reference imposes NO family constraint —
+      # it contributes "all families" to the auto-scope intersection. Reserved at
+      # the Configuration boundary (no host/group may be named "any"). Distinct
+      # from the SERVICE slot `:any`, which means "any protocol/port".
+      ANY_REFERENCE = "any"
+
+      IPV4_ADDRESS_LIST = "/ip/firewall/address-list"
+      IPV6_ADDRESS_LIST = "/ipv6/firewall/address-list"
+      IPV4_FILTER       = "/ip/firewall/filter"
+      IPV6_FILTER       = "/ipv6/firewall/filter"
+      IPV4_NAT          = "/ip/firewall/nat"
+
+      # Built-in management service set used both for the inferred backstop and
+      # as a fallback when an explicit `management service:` is not a declared
+      # Service. Maps name => [protocol, [ports]].
+      MGMT_SERVICES = {
+        "winbox" => [:tcp, [8291]],
+        "ssh" => [:tcp, [22]],
+        "api" => [:tcp, [8728]],
+        "rest" => [:tcp, [80, 443]]
+      }.freeze
+
+      # Chains assembled into the filter tables, in deterministic emit order.
+      FILTER_CHAINS = %i[input forward output].freeze
+
+      # Abstract match keys that translate straight to a row field (no host/group
+      # resolution). `:src`/`:dst` are handled separately (address-list refs).
+      SIMPLE_MATCH_KEYS = {
+        state: :connection_state, protocol: :protocol,
+        dst_port: :dst_port, src_port: :src_port,
+        in_interface: :in_interface, out_interface: :out_interface,
+        in_interface_list: :in_interface_list, out_interface_list: :out_interface_list
+      }.freeze
+
+      # Row fields that are rule ATTRIBUTES, not match content: excluded from the
+      # content-only identity tag so toggling them (e.g. log/disabled) yields a
+      # stable `(tag, ordinal)` and an in-place :update, never delete+create.
+      NON_IDENTITY_FIELDS = %i[comment log log_prefix disabled].freeze
+
+      def initialize(configuration)
+        @configuration = configuration
+      end
+
+      # @param device [Model::Device]
+      # @return [DesiredState]
+      def compile(device:)
+        @device = device
+        @flatten_cache = {}
+        @reference_families = {}
+
+        assert_no_list_name_clash!
+        assert_management_present!
+
+        rows = {}
+        emit_address_lists(rows)
+        emit_filters(rows)
+        emit_nat(rows)
+
+        build_state(rows)
+      end
+
+      # Deterministic, CONTENT-ONLY identity tag for a normalized resource row:
+      # hashes chain + normalized match + action + src/dst list references, and
+      # excludes position/order, the `comment` (which carries the tag) AND the
+      # rule-level attributes log/log_prefix/disabled (NON_IDENTITY_FIELDS) — so
+      # toggling those is an in-place :update, not a delete+create churn.
+      # Stable across runs for the same content.
+      #
+      # @param resource [Hash] the normalized resource row
+      # @return [String] e.g. "mt-wall:ab12cd34"
+      def self.identity_tag(resource)
+        material = resource.except(*NON_IDENTITY_FIELDS)
+        canonical = material.sort_by { |key, _| key.to_s }
+                            .map { |key, value| "#{key}=#{value}" }
+                            .join("
")
+        "#{MANAGED_COMMENT_PREFIX}#{Digest::SHA1.hexdigest(canonical)[0, 12]}"
+      end
+
+      # Extract the `mt-wall:<hash>` identity tag from a rendered comment, or nil.
+      # @param comment [String, nil]
+      # @return [String, nil]
+      def self.tag_in_comment(comment)
+        return nil if comment.nil?
+
+        token = comment.to_s.split(COMMENT_SEPARATOR, 2).first
+        token if token&.start_with?(MANAGED_COMMENT_PREFIX)
+      end
+
+      # The set of address-list NAMES this configuration emits (from hosts and
+      # flattened groups). Plan.diff scopes address-list ownership to these names
+      # so foreign/static lists are never diffed or deleted.
+      #
+      # @return [Array<String>] managed address-list names
+      def managed_list_names
+        (@configuration.objects.keys + @configuration.groups.keys).uniq.sort
+      end
+
+      private
+
+      attr_reader :device
+
+      # ── address-lists ────────────────────────────────────────────────────
+
+      def emit_address_lists(rows)
+        @configuration.objects.each_value do |object|
+          object.addresses.each { |address| add_address(rows, object.name, address) }
+        end
+        @configuration.groups.each_value do |group|
+          flatten_group(group.name, []).each { |address| add_address(rows, group.name, address) }
+        end
+        sort_address_lists(rows)
+      end
+
+      def sort_address_lists(rows)
+        DesiredState::ADDRESS_LIST_PATHS.each do |path|
+          next unless rows.key?(path)
+
+          rows[path] = rows[path].uniq.sort_by { |row| [row[:list], row[:address]] }
+        end
+      end
+
+      def add_address(rows, list, address)
+        path = family_of(address) == :ip4 ? IPV4_ADDRESS_LIST : IPV6_ADDRESS_LIST
+        (rows[path] ||= []) << { list: list, address: address }
+      end
+
+      # Recursively expand a group into the de-duplicated union of its members'
+      # addresses, detecting membership cycles (and self-membership) via the
+      # visited stack.
+      def flatten_group(name, stack)
+        raise ConfigurationError, "group membership cycle detected at #{name.inspect}" if stack.include?(name)
+        return @flatten_cache[name] if @flatten_cache.key?(name)
+
+        group = @configuration.groups.fetch(name)
+        next_stack = stack + [name]
+        addresses = group.members.flat_map do |member|
+          expand_member(member, name, next_stack)
+        end.uniq
+        @flatten_cache[name] = addresses
+      end
+
+      def expand_member(member, group_name, stack)
+        if @configuration.objects.key?(member)
+          @configuration.objects[member].addresses
+        elsif @configuration.groups.key?(member)
+          flatten_group(member, stack)
+        else
+          raise ConfigurationError, "group #{group_name.inspect} references undeclared member #{member.inspect}"
+        end
+      end
+
+      # ── filter tables ────────────────────────────────────────────────────
+
+      def emit_filters(rows)
+        { ip4: IPV4_FILTER, ip6: IPV6_FILTER }.each do |family, path|
+          table = FILTER_CHAINS.flat_map { |chain| build_chain(family, chain) }
+          rows[path] = dedup(table)
+        end
+      end
+
+      def build_chain(family, chain)
+        out = []
+        unless chain == :output
+          out.concat(family_essentials(family, chain))
+          out.concat(stateful_preamble(family, chain))
+          out.concat(management_rules(family)) if chain == :input
+        end
+        out.concat(operator_rules(family, chain))
+        out.concat(grant_rules(family)) if chain == :forward
+        out.concat(default_policy_rule(chain))
+        out
+      end
+
+      # IPv6 needs an ICMPv6/NDP/PMTUD essential block before any operator rule;
+      # IPv4 has none.
+      def family_essentials(family, chain)
+        return [] unless family == :ip6
+
+        ipv6_ndp_rows(chain) + ipv6_guard_rows(chain)
+      end
+
+      # NDP types 133-136 (router/neighbor solicit+advert) with a hop-limit guard.
+      def ipv6_ndp_rows(chain)
+        {
+          "133:0-255" => "router-solicitation", "134:0-255" => "router-advertisement",
+          "135:0-255" => "neighbor-solicitation", "136:0-255" => "neighbor-advertisement"
+        }.map { |options, kind| icmpv6_row(chain, options, "ICMPv6 NDP #{kind}") }
+      end
+
+      def ipv6_guard_rows(chain)
+        [
+          [:accept, { protocol: "icmpv6", icmp_options: "2:0-255" }, "ICMPv6 packet-too-big (PMTUD)"],
+          [:drop,   { src_address: "::/128" }, "drop bad IPv6 source"],
+          [:drop,   { dst_address: "::/128" }, "drop bad IPv6 destination"],
+          [:accept, { protocol: "udp", dst_port: 546 }, "DHCPv6 client"]
+        ].map { |action, fields, note| filter_row(chain: chain, action: action, fields: fields, note: note) }
+      end
+
+      def icmpv6_row(chain, icmp_options, note)
+        filter_row(chain: chain, action: :accept,
+                   fields: { protocol: "icmpv6", icmp_options: icmp_options, hop_limit: "equal:255" },
+                   note: note)
+      end
+
+      def stateful_preamble(family, chain)
+        rules = []
+        rules << fasttrack_row if family == :ip4 && chain == :forward && fasttrack_enabled?
+        rules << filter_row(chain: chain, action: :accept,
+                            fields: { connection_state: "established,related" },
+                            note: "accept established/related")
+        rules << filter_row(chain: chain, action: :drop,
+                            fields: { connection_state: "invalid" }, note: "drop invalid")
+        rules
+      end
+
+      def fasttrack_row
+        filter_row(chain: :forward, action: "fasttrack-connection",
+                   fields: { connection_state: "established,related" },
+                   note: "fasttrack established/related")
+      end
+
+      def fasttrack_enabled?
+        device.options[:fasttrack] != false
+      end
+
+      # MANAGEMENT-PROTECTION, INPUT chain only. Explicit declaration(s) are
+      # primary: emit the UNION of every declared management path. With NO
+      # explicit path the inferred backstop opens the full mgmt service set.
+      def management_rules(family)
+        if device.management.empty?
+          inferred_management_rules
+        else
+          device.management.flat_map { |mgmt| explicit_management_rules(mgmt, family) }
+        end
+      end
+
+      def explicit_management_rules(mgmt, family)
+        src = mgmt[:src]
+        return [] if src && !reference_families(src).include?(family)
+
+        management_matches(mgmt).map do |match|
+          filter_row(chain: :input, action: :accept,
+                     fields: resolve_match(match, family, "management"), note: "management")
+        end
+      end
+
+      # One match per protocol (a multi-protocol mgmt service opens each).
+      def management_matches(mgmt)
+        protocols, ports = management_protocol_ports(mgmt)
+        base = {}
+        base[:src] = mgmt[:src] if mgmt[:src]
+        return [base] if protocols.nil? || protocols.empty?
+
+        protocols.map do |protocol|
+          match = base.dup
+          match[:protocol] = protocol
+          match[:dst_port] = ports if ports && !ports.empty?
+          match
+        end
+      end
+
+      def management_protocol_ports(mgmt)
+        if mgmt[:service]
+          resolve_management_service(mgmt[:service])
+        elsif mgmt[:port]
+          [[:tcp], DSL::Validators.normalize_service_ports(mgmt[:port])]
+        else
+          [nil, nil]
+        end
+      end
+
+      def resolve_management_service(name)
+        if (service = @configuration.services[name])
+          [service.protocols, service.ports]
+        elsif (builtin = MGMT_SERVICES[name])
+          protocol, ports = builtin
+          [[protocol], ports]
+        else
+          raise ConfigurationError, "management references unknown service #{name.inspect}"
+        end
+      end
+
+      def inferred_management_rules
+        MGMT_SERVICES.map do |name, (protocol, ports)|
+          filter_row(chain: :input, action: :accept,
+                     fields: { protocol: protocol, dst_port: ports },
+                     note: "inferred management (#{name})")
+        end
+      end
+
+      def operator_rules(family, chain)
+        device.filter_rules.select { |rule| rule.chain == chain }.flat_map do |rule|
+          next [] unless filter_rule_families(rule).include?(family)
+
+          [filter_row(chain: chain, action: rule.action,
+                      fields: resolve_match(rule.match, family, "filter rule").merge(rule_attributes(rule)),
+                      note: rule.comment)]
+        end
+      end
+
+      # The address families a Layer-B device rule should emit into. AUTO-SCOPE:
+      #   * an explicit `family:` is honored verbatim (strict — resolution in
+      #     that family is then required, else fail-fast in resolve_list!);
+      #   * an unscoped rule with NO host references (pure protocol/interface
+      #     match) emits into BOTH families;
+      #   * an unscoped rule WITH host references emits ONLY into the families its
+      #     src/dst references actually resolve in (their intersection) — so a
+      #     v4-only host no longer forces a spurious v6 error. The genuine
+      #     zero-across-BOTH case (e.g. src v4-only AND dst v6-only) still
+      #     fail-fasts.
+      def filter_rule_families(rule)
+        return [rule.family] if rule.family
+
+        refs = [rule.match[:src], rule.match[:dst]].compact
+        return %i[ip4 ip6] if refs.empty?
+
+        common = refs.map { |name| reference_families(name) }.reduce(:&)
+        return common unless common.empty?
+
+        raise ConfigurationError,
+              "filter rule on #{rule.chain} references #{refs.inspect} which share no address family"
+      end
+
+      def grant_rules(family)
+        @configuration.rules.flat_map { |grant| grant_rows(grant, family) }
+      end
+
+      def grant_rows(grant, family)
+        return [] unless grant_common_families(grant).include?(family)
+
+        grant_matches(grant).map do |match|
+          filter_row(chain: :forward, action: grant.action,
+                     fields: resolve_match(match, family, "grant").merge(rule_attributes(grant)),
+                     note: grant.comment)
+        end
+      end
+
+      def grant_common_families(grant)
+        common = reference_families(grant.source) & reference_families(grant.destination)
+        return common unless common.empty?
+
+        raise ConfigurationError,
+              "grant #{grant.source.inspect} -> #{grant.destination.inspect} resolves to no rule in any family"
+      end
+
+      # A grant compiles to ONE match per service protocol (multi-protocol
+      # services, e.g. DNS = tcp+udp, fan out into one filter rule each).
+      def grant_matches(grant)
+        base = { src: grant.source, dst: grant.destination }
+        return [base] unless grant.service
+
+        service = lookup_service!(grant.service)
+        return [base] if service.protocols.empty?
+
+        service.protocols.map do |protocol|
+          match = base.dup
+          match[:protocol] = protocol
+          match[:dst_port] = service.ports unless service.ports.empty?
+          match
+        end
+      end
+
+      def lookup_service!(name)
+        @configuration.services.fetch(name) do
+          raise ConfigurationError, "grant references unknown service #{name.inspect}"
+        end
+      end
+
+      def default_policy_rule(chain)
+        policy = effective_policy_object(chain)
+        return [] unless policy
+
+        [filter_row(chain: chain, action: policy.action,
+                    fields: rule_attributes(policy), note: "default policy #{chain}")]
+      end
+
+      # Rule-level attribute fields (log / log_prefix / disabled) shared by
+      # FilterRules, grants and the default-policy row. Duck-typed: any object
+      # responding to #log / #log_prefix / #disabled. Excluded from the identity
+      # tag (NON_IDENTITY_FIELDS), so a toggle is an in-place :update.
+      #
+      # `log`/`disabled` are emitted as Ruby BOOLEANS (rendered "true"/"false" by
+      # DesiredState.normalize_value) to MATCH the RouterOS REST readback — which
+      # returns booleans as the strings "true"/"false", NOT the CLI "yes"/"no"
+      # idiom. Emitting "yes" here would never equal the device's "true" and
+      # would churn a logged/disabled rule on every apply. The field is OMITTED
+      # when false/absent: the diff is asymmetric (Plan#update_needed? compares
+      # only the desired row's keys), so the device's `disabled=false` readback on
+      # a normal rule is harmlessly ignored. The `.rsc` renderer translates these
+      # booleans back to the `yes`/`no` script idiom (Transport::Rsc).
+      def rule_attributes(rule)
+        attributes = {}
+        attributes[:log] = true if rule.log
+        attributes[:log_prefix] = rule.log_prefix if rule.log_prefix
+        attributes[:disabled] = true if rule.disabled
+        attributes
+      end
+
+      # ── NAT table (IPv4 only) ────────────────────────────────────────────
+
+      def emit_nat(rows)
+        return if device.nat_rules.empty?
+
+        rows[IPV4_NAT] = dedup(device.nat_rules.map { |nat| nat_row(nat) })
+      end
+
+      def nat_row(nat)
+        tagged_row({ chain: nat.chain.to_s, action: nat_action(nat.action) }.merge(nat_fields(nat)), nat.comment)
+      end
+
+      def nat_fields(nat)
+        fields = resolve_match(nat.match, :ip4, "nat rule")
+        fields[:to_addresses] = nat.to_addresses unless nat.to_addresses.empty?
+        fields[:to_ports] = nat.to_ports unless nat.to_ports.nil?
+        fields
+      end
+
+      def nat_action(action)
+        { masquerade: "masquerade", dst_nat: "dst-nat", src_nat: "src-nat" }.fetch(action, action.to_s)
+      end
+
+      # ── shared row construction ──────────────────────────────────────────
+
+      def filter_row(chain:, action:, fields: {}, note: nil)
+        tagged_row({ chain: chain.to_s, action: action.to_s }.merge(fields), note)
+      end
+
+      # Normalize a row, derive its content-only identity tag, then merge that
+      # tag with the operator note into the rendered `comment`.
+      def tagged_row(row, note)
+        normalized = DesiredState.normalize_row(row)
+        tag = self.class.identity_tag(normalized)
+        normalized[:comment] = merge_comment(tag, note)
+        normalized
+      end
+
+      def merge_comment(tag, note)
+        note.nil? || note.to_s.empty? ? tag : "#{tag}#{COMMENT_SEPARATOR}#{note}"
+      end
+
+      # Translate an abstract match Hash into row fields, resolving src/dst host/
+      # group references to address-list names and failing fast on zero family
+      # resolution.
+      def resolve_match(match, family, context)
+        match.each_with_object({}) do |(key, value), out|
+          field = SIMPLE_MATCH_KEYS[key]
+          if field
+            out[field] = value
+          else
+            out.merge!(resolve_address_match(key, value, family, context))
+          end
+        end
+      end
+
+      def resolve_address_match(key, value, family, context)
+        case key
+        when :src then any_reference?(value) ? {} : { src_address_list: resolve_list!(value, family, context) }
+        when :dst then any_reference?(value) ? {} : { dst_address_list: resolve_list!(value, family, context) }
+        else raise ConfigurationError, "unsupported match condition #{key.inspect}"
+        end
+      end
+
+      # @return [Boolean] true if the reference is the reserved match-all "any".
+      def any_reference?(name)
+        name == ANY_REFERENCE
+      end
+
+      def resolve_list!(name, family, context)
+        unless reference_families(name).include?(family)
+          raise ConfigurationError,
+                "#{context} references #{name.inspect} which has no #{family} addresses"
+        end
+        name
+      end
+
+      # Families (subset of [:ip4, :ip6]) for which a host/group reference has
+      # addresses. Fails fast on an unknown or empty reference. The reserved
+      # match-all "any" imposes NO family constraint, so it reports ALL families
+      # — intersecting it with the other endpoint is a no-op, which is exactly
+      # the desired auto-scope behavior (any -> v4-only host emits v4 only;
+      # any -> any emits both).
+      def reference_families(name)
+        return DSL::Validators::FAMILIES if any_reference?(name)
+
+        @reference_families[name] ||= compute_reference_families(name)
+      end
+
+      def compute_reference_families(name)
+        addresses = addresses_for_reference(name)
+        raise ConfigurationError, "reference #{name.inspect} resolves to no addresses" if addresses.empty?
+
+        addresses.map { |address| family_of(address) }.uniq
+      end
+
+      def addresses_for_reference(name)
+        if @configuration.objects.key?(name)
+          @configuration.objects[name].addresses
+        elsif @configuration.groups.key?(name)
+          flatten_group(name, [])
+        else
+          raise ConfigurationError, "reference to undeclared host/group #{name.inspect}"
+        end
+      end
+
+      # ── validation / helpers ─────────────────────────────────────────────
+
+      def assert_no_list_name_clash!
+        clash = @configuration.objects.keys & @configuration.groups.keys
+        return if clash.empty?
+
+        raise ConfigurationError,
+              "name(s) #{clash.inspect} used by both a host and a group; they would collide as one address-list"
+      end
+
+      def assert_management_present!
+        return unless device.management.empty?
+        return unless input_locked?
+
+        raise ConfigurationError,
+              "device #{device.name.inspect} locks its input chain (policy :input, :drop) " \
+              "but declares no `management`; declare one to avoid lockout"
+      end
+
+      def input_locked?
+        effective_policy(:input) == :drop
+      end
+
+      def effective_policy_object(chain)
+        device.policies.find { |policy| policy.chain == chain } ||
+          @configuration.global_policies.find { |policy| policy.chain == chain }
+      end
+
+      def effective_policy(chain)
+        effective_policy_object(chain)&.action
+      end
+
+      def family_of(address)
+        DSL::Validators.infer_family(address)
+      end
+
+      # Collapse EXACT duplicates (same content+chain => same tag) into one row,
+      # preserving first-occurrence order (order is load-bearing in RouterOS).
+      def dedup(table)
+        seen = Set.new
+        table.select { |row| seen.add?(self.class.identity_tag(row)) }
+      end
+
+      def build_state(rows)
+        state = DesiredState.new
+        rows.each do |path, list|
+          list.each { |row| state.add(path, row) }
+        end
+        state
+      end
+    end
+  end
+end