mt-wall 0.1.0

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

@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module Mt
+  module Wall
+    module DSL
+      # Shared fail-fast validation/normalization helpers for the DSL capture
+      # layer. Every value that reaches a Model::* object passes through here so
+      # that typos surface loudly AND so that hostile values cannot inject into a
+      # later rendered `.rsc` / JSON payload (names are charset-restricted,
+      # addresses must parse via stdlib IPAddr, ports are bounded, protocols are
+      # allowlisted). All failures raise Mt::Wall::ConfigurationError.
+      module Validators # rubocop:disable Metrics/ModuleLength
+        # Strict identifier charset shared by host/group/service/interface names.
+        NAME_RE = /\A[\w.-]+\z/
+
+        # Charset allowed in a firewall `log-prefix` label. Restricted (no shell/
+        # rsc/JSON metacharacters) so the value cannot inject into a rendered
+        # `.rsc` script or REST payload; spaces and a few separators are allowed
+        # because operators routinely use them in prefixes.
+        LOG_PREFIX_RE = %r{\A[\w .:/-]{1,64}\z}
+
+        # Protocols accepted in `protocol:` match conditions / services.
+        PROTOCOLS = %i[
+          tcp udp icmp icmpv6 igmp gre esp ah sctp ospf vrrp pim
+          ipsec-esp ipsec-ah l2tp ipencap ddp udplite
+        ].freeze
+
+        # Connection-tracking states accepted in `state:`.
+        STATES = %i[established related invalid new untracked].freeze
+
+        # Firewall chains (policy + Layer-B chain blocks).
+        CHAINS = %i[input output forward].freeze
+
+        # Chain default policy actions.
+        POLICY_ACTIONS = %i[accept drop].freeze
+
+        # Address families.
+        FAMILIES = %i[ip4 ip6].freeze
+
+        module_function
+
+        # Validate a strict identifier (host/group/service/interface name).
+        # @return [String] the validated name
+        def validate_name!(name, label: "name")
+          str = name.to_s
+          unless NAME_RE.match?(str)
+            raise ConfigurationError,
+                  "invalid #{label} #{name.inspect}: must match #{NAME_RE.inspect}"
+          end
+          str
+        end
+
+        # Validate a group token used as host-side membership. Guards the common
+        # `host "web", "10.0.0.5"` slip where an address is passed where a group
+        # name is expected.
+        # @return [String]
+        def validate_group_token!(token)
+          if looks_like_address?(token)
+            raise ConfigurationError,
+                  "#{token.inspect} looks like an address — did you mean `address:`?"
+          end
+          validate_name!(token, label: "group")
+        end
+
+        # @return [Boolean] true if the token parses as an IP address / CIDR.
+        def looks_like_address?(token)
+          IPAddr.new(token.to_s)
+          true
+        rescue StandardError
+          false
+        end
+
+        # Infer the address family of an address/CIDR/range, validating it parses.
+        # For a range, the family is taken from its (validated, same-family)
+        # endpoints.
+        # @return [Symbol] :ip4 or :ip6
+        def infer_family(address)
+          str = address.to_s
+          return range_endpoints(str).first.ipv4? ? :ip4 : :ip6 if range?(str)
+
+          parse_address(str).ipv4? ? :ip4 : :ip6
+        end
+
+        # Validate an IPv4/IPv6 address, CIDR subnet, OR IP range
+        # (`10.0.0.1-10.0.0.10`, both endpoints the same family).
+        # @return [String] the original address string
+        def validate_address!(address)
+          str = address.to_s
+          range?(str) ? validate_range!(str) : parse_address(str)
+          str
+        end
+
+        # @return [Boolean] true if the token is an IP RANGE (`low-high`).
+        def range?(token)
+          token.to_s.include?("-")
+        end
+
+        # Validate an IP range: both endpoints parse and share one family.
+        # @return [String] the original range string
+        def validate_range!(range)
+          low, high = range_endpoints(range)
+          if low.ipv4? != high.ipv4?
+            raise ConfigurationError, "address range #{range.inspect} mixes IPv4 and IPv6 endpoints"
+          end
+
+          range.to_s
+        end
+
+        # Parse the two endpoints of a `low-high` range into IPAddr objects.
+        # @return [Array(IPAddr, IPAddr)]
+        def range_endpoints(range)
+          low, high, extra = range.to_s.split("-", 3)
+          raise ConfigurationError, "invalid address range #{range.inspect}" if high.nil? || extra
+
+          [parse_address(low), parse_address(high)]
+        end
+
+        # Validate an IPv4-only address/CIDR (NAT targets, v1).
+        # @return [String]
+        def validate_ipv4!(address)
+          unless parse_address(address).ipv4?
+            raise ConfigurationError,
+                  "IPv6 NAT target #{address.inspect} is not supported (NAT is IPv4-only in v1)"
+          end
+          address.to_s
+        end
+
+        # Parse an address/CIDR via IPAddr, normalizing failures to
+        # ConfigurationError. IPAddr::Error descends from ArgumentError.
+        # @return [IPAddr]
+        def parse_address(address)
+          IPAddr.new(address.to_s)
+        rescue ArgumentError
+          raise ConfigurationError, "invalid address #{address.inspect}"
+        end
+
+        # @return [Symbol] the validated protocol symbol
+        def validate_protocol!(protocol)
+          sym = protocol.to_s.downcase.to_sym
+          unless PROTOCOLS.include?(sym)
+            raise ConfigurationError,
+                  "unknown protocol #{protocol.inspect}; allowed: #{PROTOCOLS.join(', ')}"
+          end
+          sym
+        end
+
+        # @return [Symbol] the validated chain symbol
+        def validate_chain!(chain)
+          sym = chain.to_s.to_sym
+          raise ConfigurationError, "invalid chain #{chain.inspect}" unless CHAINS.include?(sym)
+
+          sym
+        end
+
+        # @return [Symbol] the validated policy action symbol (:accept/:drop)
+        def validate_policy_action!(action)
+          sym = action.to_s.to_sym
+          unless POLICY_ACTIONS.include?(sym)
+            raise ConfigurationError, "invalid policy action #{action.inspect}; use :accept or :drop"
+          end
+
+          sym
+        end
+
+        # @return [Symbol] the validated family symbol
+        def validate_family!(family)
+          sym = family.to_s.to_sym
+          raise ConfigurationError, "invalid family #{family.inspect}; use :ip4 or :ip6" unless FAMILIES.include?(sym)
+
+          sym
+        end
+
+        # Validate a boolean rule flag (`log:` / `disabled:`). nil is treated as
+        # false (the default); anything other than true/false fails fast.
+        # @return [Boolean]
+        def validate_flag!(value, label: "flag")
+          return false if value.nil? || value == false
+          return true if value == true
+
+          raise ConfigurationError, "#{label} must be true or false, got #{value.inspect}"
+        end
+
+        # Validate+normalize the shared rule-level attribute keywords
+        # (`log:`/`log_prefix:`/`disabled:`) into a kwargs Hash ready to splat
+        # into a Model::* (FilterRule / Rule / Policy). Keeps the flag handling
+        # DRY across the chain/rule/policy DSL verbs.
+        # @return [Hash]
+        def rule_flags(log: false, log_prefix: nil, disabled: false)
+          {
+            log: validate_flag!(log, label: "log"),
+            log_prefix: log_prefix && validate_log_prefix!(log_prefix),
+            disabled: validate_flag!(disabled, label: "disabled")
+          }
+        end
+
+        # Validate a firewall `log-prefix` label against LOG_PREFIX_RE.
+        # @return [String] the validated prefix
+        def validate_log_prefix!(prefix)
+          str = prefix.to_s
+          unless LOG_PREFIX_RE.match?(str)
+            raise ConfigurationError,
+                  "invalid log_prefix #{prefix.inspect}: must match #{LOG_PREFIX_RE.inspect}"
+          end
+          str
+        end
+
+        # @return [Array<Symbol>] normalized, validated connection states
+        def normalize_states(state)
+          Array(state).map do |s|
+            sym = s.to_s.to_sym
+            raise ConfigurationError, "invalid connection state #{s.inspect}" unless STATES.include?(sym)
+
+            sym
+          end
+        end
+
+        # Validate a port specification (Integer, Array, Range or "a-b"/"n"
+        # String, nested arrays allowed) without altering it.
+        # @return the original ports value
+        def validate_ports!(ports)
+          collect_ports(ports, [])
+          ports
+        end
+
+        # Validate and expand a service port specification into a flat, sorted,
+        # de-duplicated Array<Integer> (Model::Service stores discrete ports).
+        # @return [Array<Integer>]
+        def normalize_service_ports(ports)
+          out = []
+          collect_ports(ports, out)
+          out.uniq.sort
+        end
+
+        # @return [Integer] the validated port
+        def port_in_range!(port)
+          unless port.is_a?(Integer) && port.between?(1, 65_535)
+            raise ConfigurationError, "port out of range (1..65535): #{port.inspect}"
+          end
+
+          port
+        end
+
+        # Validate, and optionally normalize, a match-condition Hash for a
+        # Layer-B filter/nat rule. Unknown keys fail fast.
+        # @return [Hash] the normalized match
+        def normalize_match(match, allow_state: true)
+          match.each_with_object({}) do |(key, value), normalized|
+            normalized[key] = normalize_match_value(key, value, allow_state: allow_state)
+          end
+        end
+
+        # rubocop:disable Metrics/MethodLength
+        def normalize_match_value(key, value, allow_state:)
+          case key
+          when :state
+            raise ConfigurationError, "`state:` is not valid for a NAT rule" unless allow_state
+
+            normalize_states(value)
+          when :protocol
+            validate_protocol!(value)
+          when :dst_port, :src_port
+            validate_ports!(value)
+            value
+          when :in_interface, :out_interface, :in_interface_list, :out_interface_list, :src, :dst
+            validate_name!(value, label: key.to_s)
+          else
+            raise ConfigurationError, "unknown match condition #{key.inspect}"
+          end
+        end
+        # rubocop:enable Metrics/MethodLength
+
+        # Recursively validate (and collect into +out+) every port in a port
+        # specification, expanding Ranges and "a-b"/"n" Strings.
+        # rubocop:disable Metrics/MethodLength
+        def collect_ports(value, out)
+          case value
+          when Integer
+            out << port_in_range!(value)
+          when Range
+            value.each { |port| out << port_in_range!(port) }
+          when String
+            collect_string_ports(value, out)
+          when Array
+            value.each { |element| collect_ports(element, out) }
+          else
+            raise ConfigurationError, "invalid port specification #{value.inspect}"
+          end
+        end
+        # rubocop:enable Metrics/MethodLength
+
+        def collect_string_ports(value, out)
+          case value
+          when /\A(\d+)-(\d+)\z/
+            (Regexp.last_match(1).to_i..Regexp.last_match(2).to_i).each { |port| out << port_in_range!(port) }
+          when /\A\d+\z/
+            out << port_in_range!(value.to_i)
+          else
+            raise ConfigurationError, "invalid port specification #{value.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mt/wall/dsl.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Mt
+  module Wall
+    # Entry points for turning DSL (a block or files) into a Configuration.
+    # The actual verbs live in DSL::RootBuilder.
+    module DSL
+      module_function
+
+      # Build a Configuration from a DSL block.
+      #
+      #   Mt::Wall::DSL.build do
+      #     host "web", address: ["10.0.0.5", "10.0.1.0/24"]
+      #   end
+      #
+      # @return [Configuration]
+      def build(&block)
+        config = Configuration.new
+        RootBuilder.new(config).instance_eval(&block) if block
+        config
+      end
+
+      # Load and evaluate one or more DSL sources into a SINGLE Configuration
+      # (a GitOps repo of config). Each path may be either a `*.rb` file or a
+      # DIRECTORY; a directory contributes every `*.rb` file found under it
+      # RECURSIVELY, in deterministic SORTED (lexicographic) order so the same
+      # repo always loads the same way. Files supplied directly are loaded in
+      # the order given; the contents of a directory are sorted among
+      # themselves. All sources fold into one shared Configuration.
+      #
+      # @param paths [Array<String>] DSL files and/or directories
+      # @raise [ConfigurationError] when a path does not exist
+      # @return [Configuration]
+      def load(*paths)
+        config = Configuration.new
+        builder = RootBuilder.new(config)
+        expand(paths.flatten).each { |path| builder.instance_eval(File.read(path), path) }
+        config
+      end
+
+      # Resolve the given paths into an ordered list of concrete `*.rb` files:
+      # files pass through untouched; directories expand to their recursive,
+      # sorted `*.rb` contents. Fails fast on a missing path.
+      # @param paths [Array<String>]
+      # @return [Array<String>]
+      def expand(paths)
+        paths.flat_map do |path|
+          if File.directory?(path)
+            # Dir.glob returns lexicographically sorted results (Ruby 3.0+),
+            # giving a deterministic, repeatable load order across a GitOps repo.
+            Dir.glob(File.join(path, "**", "*.rb"))
+          elsif File.file?(path)
+            [path]
+          else
+            raise ConfigurationError, "no such DSL path #{path.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mt/wall/errors.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Mt
+  module Wall
+    # Base class for every error raised by the gem.
+    class Error < StandardError; end
+
+    # Raised when the DSL / Configuration is invalid (unknown reference,
+    # duplicate name, missing required attribute, ...).
+    class ConfigurationError < Error; end
+
+    # Raised when a transport cannot talk to a device or gets an
+    # unexpected response.
+    class TransportError < Error; end
+
+    # Raised when a Plan cannot be built or applied.
+    class PlanError < Error; end
+  end
+end

data/lib/mt/wall/model/address_object.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Mt
+  module Wall
+    module Model
+      # A named firewall object: a label bound to one or more IP addresses
+      # or CIDR subnets. Compiles to entries in a RouterOS
+      # `/ip firewall address-list`. The same address may belong to many
+      # objects (one IP -> many list memberships), which is native to
+      # address-lists.
+      #
+      # ADDRESS FAMILY (IPv4 vs IPv6) is INFERRED per address via the stdlib
+      # `IPAddr` — there are no separate v4/v6 verbs and a single object MAY
+      # hold a mix of families. The Compiler partitions the addresses by family
+      # so that IPv4 entries land in `/ip/firewall/address-list` and IPv6
+      # entries in `/ipv6/firewall/address-list` (see Compiler / DesiredState).
+      #
+      # VALIDATION (fail-fast at the DSL/model boundary): `name` must match the
+      # strict charset `\A[\w.-]+\z`; every entry in `addresses` must be a valid
+      # single address, a CIDR subnet, OR an IP RANGE (`10.0.0.1-10.0.0.10`, both
+      # endpoints the same family) — each form parses via `IPAddr` (this also
+      # neutralizes .rsc / JSON injection). FQDN address-list entries are OUT OF
+      # SCOPE for v1 (future). An object with NO addresses is an error.
+      #
+      # @!attribute name      [String]        unique object name / address-list name
+      # @!attribute addresses [Array<String>] IPv4/IPv6 addresses, CIDR subnets or IP ranges
+      # @!attribute comment   [String, nil]   optional human-readable note
+      AddressObject = Data.define(:name, :addresses, :comment) do
+        def initialize(name:, addresses: [], comment: nil)
+          super(name: name, addresses: Array(addresses), comment: comment)
+        end
+      end
+    end
+  end
+end

data/lib/mt/wall/model/device.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Mt
+  module Wall
+    module Model
+      # A managed RouterOS device.
+      #
+      # SECURITY: credentials are NEVER stored here or in the DSL/git. The
+      # `transport` names which adapter to use (e.g. :rest_api); the adapter
+      # reads its credentials from ENV at apply time.
+      #
+      # Configures the box's OWN firewall (Layer B): chain defaults and the
+      # input/output/forward filter rules of this specific router. The abstract
+      # access grants (Layer A, Model::Rule) are device-agnostic and live on the
+      # Configuration — the Compiler injects them into this device's forward
+      # chain; they are NOT stored here.
+      #
+      # NAT (Layer B, per-box): the device may also declare `/ip firewall nat`
+      # rules via the `nat do … end` block. These are IPv4-only for v1 (see
+      # Model::NatRule) and stored alongside the filter rules here.
+      #
+      # MANAGEMENT PROTECTION: `management` records the operator's EXPLICIT
+      # declaration of the mgmt traffic the input-chain safe preamble must keep
+      # open (so an apply can never cause lockout). It is an ARRAY of small
+      # spec Hashes `{ src:, service:, port: }` (any key optional), default `[]`
+      # — REPEATABLE, so a device can protect several paths at once (e.g. an SSH
+      # admin AND a REST/CI apply channel). The Compiler emits the UNION of all
+      # specs. EXPLICIT is PRIMARY and a NON-EMPTY array is REQUIRED when the
+      # device locks its input chain (`policy :input, :drop`) — the Compiler
+      # fails fast if it is empty. Transport inference (full mgmt service set,
+      # both families) is only a best-effort BACKSTOP used when the array is
+      # empty, and is never authoritative for a locked input chain.
+      # Set via DeviceBuilder#management.
+      #
+      # @!attribute name         [String]            unique device name
+      # @!attribute host         [String]            hostname / IP of the router
+      # @!attribute transport    [Symbol]            transport adapter key (e.g. :rest_api, :rsc)
+      # @!attribute policies     [Array<Policy>]     per-device chain-default overrides
+      # @!attribute filter_rules [Array<FilterRule>] the box's own input/output/forward rules
+      # @!attribute nat_rules    [Array<NatRule>]    the box's own srcnat/dstnat rules (IPv4-only, v1)
+      # @!attribute management   [Array<Hash>]       explicit mgmt-protect specs { src:, service:, port: }
+      # @!attribute options      [Hash]              non-secret transport options (port, verify_tls, ...)
+      Device = Data.define(:name, :host, :transport, :policies, :filter_rules, :nat_rules,
+                           :management, :options) do
+        def initialize(name:, host:, transport: :rest_api, policies: [], filter_rules: [],
+                       nat_rules: [], management: [], options: {})
+          super(name: name, host: host, transport: transport,
+                policies: Array(policies), filter_rules: Array(filter_rules),
+                nat_rules: Array(nat_rules), management: Array(management), options: options)
+        end
+      end
+    end
+  end
+end

data/lib/mt/wall/model/filter_rule.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Mt
+  module Wall
+    module Model
+      # A device-local firewall rule on one chain (Layer B — the box's own
+      # firewall). Unlike Model::Rule (the abstract, device-agnostic access
+      # grant), a FilterRule maps almost directly to a single RouterOS
+      # `/ip firewall filter` (or `/ipv6/firewall/filter`) rule: a chain, an
+      # action, and native match conditions.
+      #
+      # `match` is a normalized Hash of conditions. Supported keys:
+      #   :state         [Array<Symbol>] connection states (:established,
+      #                                  :related, :invalid, :new, :untracked)
+      #   :protocol      [Symbol]        :tcp, :udp, :icmp, ...
+      #   :dst_port      [Integer, Array, Range]
+      #   :src_port      [Integer, Array, Range]
+      #   :in_interface  [String]
+      #   :out_interface [String]
+      #   :in_interface_list  [String]   RouterOS /interface/list name (referenced)
+      #   :out_interface_list [String]   RouterOS /interface/list name (referenced)
+      #   :src           [String]        host/group name -> src-address-list
+      #   :dst           [String]        host/group name -> dst-address-list
+      #
+      # DUAL-STACK: `family` scopes the rule to one address family. `nil` (the
+      # default) means BOTH — the Compiler emits the rule into the v4 filter
+      # table AND the v6 filter table. `:ip4` / `:ip6` restrict it to a single
+      # family (e.g. an ICMPv6-only rule). The optional `family:` keyword on the
+      # `accept`/`drop`/`reject` ChainBuilder verbs sets this.
+      #
+      # RULE IDENTITY: mt-wall owns the ENTIRE filter table, so apply REPLACES
+      # it wholesale. To survive that, every emitted rule carries a deterministic
+      # identity tag `mt-wall:<stable-hash>` in its RouterOS `comment` field. The
+      # hash is CONTENT-ONLY — chain + normalized match + action + src/dst list
+      # references — and EXCLUDES position/order. Diff/Plan match desired vs.
+      # current by this tag, NOT by the opaque/unstable device-assigned `.id`.
+      # Ordering is a separate Plan concern (the :move op + Operation#position),
+      # so a pure reorder neither changes the tag nor churns as delete+create.
+      # The `comment` attribute here is the OPERATOR's human-readable note; the
+      # Compiler merges it with the machine tag when rendering the device
+      # `comment` (e.g. `"mt-wall:ab12cd34 | allow ssh from admin"`).
+      #
+      # RULE-LEVEL ATTRIBUTES (NOT match conditions): `log` / `log_prefix` and
+      # `disabled` configure HOW a rule behaves, not WHICH packets it matches.
+      # They are EXCLUDED from the content-only identity tag (see Compiler), so
+      # toggling them on an otherwise unchanged rule yields a stable identity and
+      # an in-place :update — never a delete+create churn. They compile to the
+      # RouterOS `log` / `log-prefix` / `disabled` row fields.
+      #
+      # @!attribute chain      [Symbol]      :input, :output or :forward
+      # @!attribute action     [Symbol]      :accept, :drop or :reject
+      # @!attribute match      [Hash]        native match conditions (see above)
+      # @!attribute family     [Symbol, nil] :ip4, :ip6 or nil (both families)
+      # @!attribute comment    [String, nil] optional operator-authored note
+      # @!attribute log        [Boolean]     log matched packets (RouterOS log=yes)
+      # @!attribute log_prefix [String, nil] optional log-prefix label
+      # @!attribute disabled   [Boolean]     keep the rule but inactive (disabled=yes)
+      FilterRule = Data.define(:chain, :action, :match, :family, :comment, :log, :log_prefix, :disabled) do
+        def initialize(chain:, action:, match: {}, family: nil, comment: nil,
+                       log: false, log_prefix: nil, disabled: false)
+          super
+        end
+      end
+    end
+  end
+end

data/lib/mt/wall/model/group.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Mt
+  module Wall
+    module Model
+      # A named collection of AddressObjects and/or other Groups.
+      #
+      # RouterOS address-lists are NOT nestable, so groups have no native
+      # equivalent: the Compiler FLATTENS a group into the union of its
+      # members' addresses (recursively expanding nested groups). This
+      # flattening is the central responsibility of the Compiler.
+      #
+      # @!attribute name    [String]        unique group name
+      # @!attribute members [Array<String>] names of objects and/or groups
+      # @!attribute comment [String, nil]   optional human-readable note
+      # NOTE: the `:members` Data member intentionally shadows Data#members
+      # (the auto-generated list of member NAMES). Renaming would break the
+      # domain-meaningful public API (`group.members` = the group's contents),
+      # so the Lint/DataDefineOverride warning is suppressed here on purpose.
+      Group = Data.define(:name, :members, :comment) do # rubocop:disable Lint/DataDefineOverride
+        def initialize(name:, members: [], comment: nil)
+          super(name: name, members: Array(members), comment: comment)
+        end
+      end
+    end
+  end
+end

data/lib/mt/wall/model/nat_rule.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Mt
+  module Wall
+    module Model
+      # A device-local NAT rule (Layer B — the box's own firewall). Compiles
+      # almost directly to a single RouterOS `/ip firewall nat` rule: a chain,
+      # an action, native match conditions, and translation targets.
+      #
+      # IPv4-ONLY for v1: RouterOS keeps NAT under `/ip/firewall/nat`. IPv6 NAT
+      # (`/ipv6/firewall/nat`) is intentionally OUT OF SCOPE for v1 — a NatRule
+      # always targets the v4 table. Validation rejects IPv6 match/translation
+      # addresses.
+      #
+      # `match` is a normalized Hash of conditions, reusing the FilterRule key
+      # set where it makes sense:
+      #   :protocol      [Symbol]            :tcp, :udp, ...
+      #   :dst_port      [Integer, Array, Range]  the published/external port(s)
+      #   :src_port      [Integer, Array, Range]
+      #   :in_interface  [String]            e.g. the WAN interface (masquerade)
+      #   :out_interface [String]
+      #   :src           [String]            host/group name -> src-address-list
+      #   :dst           [String]            host/group name -> dst-address-list
+      #
+      # Translation targets (action-dependent):
+      #   * :masquerade            — ignores to_addresses/to_ports
+      #   * :dst_nat (port-forward) — to_addresses + to_ports = the internal host:port
+      #   * :src_nat                — to_addresses (+ optional to_ports)
+      #
+      # RULE IDENTITY: like FilterRule, mt-wall owns the ENTIRE nat table, so
+      # every emitted rule carries the deterministic `mt-wall:<stable-hash>`
+      # identity tag in its `comment`; diff/Plan match by tag, never by `.id`.
+      #
+      # @!attribute chain        [Symbol]      :srcnat or :dstnat
+      # @!attribute action       [Symbol]      :masquerade, :dst_nat or :src_nat
+      #                                        (rendered to RouterOS "dst-nat" / "src-nat")
+      # @!attribute match        [Hash]        native match conditions (see above)
+      # @!attribute to_addresses [Array<String>] IPv4 translation target address(es)
+      # @!attribute to_ports     [Integer, Array, Range, nil] translation target port(s)
+      # @!attribute comment      [String, nil] optional operator-authored note
+      NatRule = Data.define(:chain, :action, :match, :to_addresses, :to_ports, :comment) do
+        def initialize(chain:, action:, match: {}, to_addresses: [], to_ports: nil, comment: nil)
+          super(chain: chain, action: action, match: match,
+                to_addresses: Array(to_addresses), to_ports: to_ports, comment: comment)
+        end
+      end
+    end
+  end
+end

data/lib/mt/wall/model/policy.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Mt
+  module Wall
+    module Model
+      # A default policy for a firewall chain, e.g. Policy.new(chain: :forward,
+      # action: :drop). Defined globally on the Configuration and optionally
+      # overridden per Device. Compiles to the trailing default rule of a chain.
+      #
+      # RULE-LEVEL ATTRIBUTES (NOT match conditions): `log` / `log_prefix` and
+      # `disabled` configure the trailing default-policy rule and are excluded
+      # from the content-only identity tag (toggling them is an in-place :update).
+      #
+      # @!attribute chain      [Symbol]      :input, :forward or :output
+      # @!attribute action     [Symbol]      :accept or :drop
+      # @!attribute comment    [String, nil] optional human-readable note
+      # @!attribute log        [Boolean]     log packets hitting the default (log=yes)
+      # @!attribute log_prefix [String, nil] optional log-prefix label
+      # @!attribute disabled   [Boolean]     keep but inactive (disabled=yes)
+      Policy = Data.define(:chain, :action, :comment, :log, :log_prefix, :disabled) do
+        def initialize(chain:, action:, comment: nil, log: false, log_prefix: nil, disabled: false)
+          super
+        end
+      end
+    end
+  end
+end