protege 0.1.0.alpha.1

data/lib/protege/gateway/access_control.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Protege
+  module Gateway
+    # The inbound access guardrail: composes every access-policy *layer* that applies to a persona and
+    # answers the one question the Gateway asks — may this sender reach this persona? A gateway concern
+    # (inbound mail authorization), it lives beside the other Gateway protocol pieces and is called from
+    # the Gateway's inbound edge, +AgentMailbox+.
+    #
+    # Composition is by **intersection**: a sender is permitted only when *every* layer permits it
+    # (logical AND). Because intersection is commutative there is no precedence to reason about — the
+    # order of layers never changes the outcome — and the security property falls out for free: a layer
+    # can only *narrow* the set of admitted senders, never widen it. So a per-persona rule can tighten
+    # who reaches that agent but can never punch through the committed org-wide ceiling.
+    #
+    # Two layers exist today — the committed global policy (+Protege.configuration.inbound_access+) and
+    # the persona's runtime rules (+AccessRule.policy_for+). This composer is the single seam the rest of
+    # the engine calls; adding a layer later (e.g. a per-persona-class committed policy) is a one-line
+    # change to {#policies}, never a change at the call sites.
+    #
+    # @example Gate an inbound sender
+    #   Gateway::AccessControl.for(persona:).permits?(address: mail.from.first)
+    class AccessControl
+      # @return [Protege::Persona] the persona the inbound mail is addressed to
+      attr_reader :persona
+
+      class << self
+        # Build the access control for a persona. Factory mirror of +.new+ reading as a lookup.
+        #
+        # @param persona [Protege::Persona] the routed persona
+        # @return [Protege::Gateway::AccessControl] the composed guardrail
+        def for(persona:)
+          new(persona:)
+        end
+      end
+
+      # @param persona [Protege::Persona] the routed persona
+      # @return [void]
+      def initialize(persona:)
+        @persona = persona
+      end
+
+      # Decide whether a sender may reach this persona, intersecting all applicable layers.
+      #
+      # @param address [String] the raw sender address
+      # @return [Boolean] true only when every layer permits the sender
+      def permits?(address:)
+        policies.all? { |policy| policy.permits?(address:) }
+      end
+
+      private
+
+      # The ordered (order-immaterial) list of policy layers that apply to this persona.
+      #
+      # Add a layer here — and only here — to extend the guardrail.
+      #
+      # @return [Array<Protege::Gateway::AccessPolicy>] the global ceiling and the persona's runtime policy
+      def policies
+        [
+          Protege.configuration.inbound_access,
+          AccessRule.policy_for(persona)
+        ]
+      end
+    end
+  end
+end

data/lib/protege/gateway/access_policy.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Protege
+  module Gateway
+    # One layer of the inbound access-control guardrail: an immutable value that decides whether a given
+    # sender address is permitted, given an allow-list and a deny-list of address patterns. A Gateway
+    # value type (inbound authorization) — built through the +Gateway.build_access_policy+ factory,
+    # composed by +Gateway::AccessControl+, and assigned as the global ceiling via +config.inbound_access+
+    # or per-persona by +AccessRule.policy_for+:
+    #
+    #   config.inbound_access = Protege::Gateway.build_access_policy(allow: ['*@company.co'])
+    #
+    # A policy is evaluated in a fixed precedence — an explicit +deny+ match always wins, then an
+    # +allow+ match admits, then the +default_decision+ settles everyone else. The default is *derived*
+    # when not given: the mere presence of an allow rule flips the layer into allow-list mode
+    # (default-deny), which is the intuitive reading of "only these may enter". With no allow rules the
+    # default is +:allow+, so a layer carrying only deny rules behaves as a block-list.
+    #
+    # Patterns are matched against the sender's tag-stripped, lowercased +local@domain+ routing key (so
+    # +ceo+finance@Company.CO+ matches a +ceo@company.co+ rule), and support a single +*+ wildcard
+    # (e.g. +*@company.co+). This object knows nothing about layering; composing several policies into
+    # the org→persona guardrail is +AccessControl+'s job.
+    #
+    # @example The identity policy — a bare +build_access_policy+ permits everyone (empty lists derive a
+    #   default-allow), so it drops out of the +AccessControl+ intersection as a no-op.
+    AccessPolicy = Data.define(:allow, :deny, :default_decision) do
+      # Build a policy, normalizing the pattern lists and deriving the default decision.
+      #
+      # @param allow [Array<String>] allow-list patterns (blank/nil entries are dropped)
+      # @param deny [Array<String>] deny-list patterns (blank/nil entries are dropped)
+      # @param default_decision [Symbol, nil] +:allow+/+:deny+; when +nil+, derived from +allow+
+      #   (present → +:deny+, empty → +:allow+)
+      def initialize(allow: [], deny: [], default_decision: nil)
+        allow              = normalize_patterns(allow)
+        deny               = normalize_patterns(deny)
+        # Derive the default decision when not given: if any allow rules exist, default-deny;
+        # otherwise default-allow.
+        default_decision ||= allow.empty? ? :allow : :deny
+
+        super
+      end
+
+      # Decide whether a sender address is permitted by this layer.
+      #
+      # @param address [String] the raw sender address (display name, plus-tag, and case tolerated)
+      # @return [Boolean] true when the sender may pass this layer
+      def permits?(address:)
+        key = routing_key_for(address)
+
+        return false if deny.any?  { |pattern| matches?(pattern:, key:) }
+        return true  if allow.any? { |pattern| matches?(pattern:, key:) }
+
+        default_decision == :allow
+      end
+
+      private
+
+      # Normalize a raw pattern list: stringify, strip, downcase, and drop blanks.
+      #
+      # @param patterns [Array<String, nil>] the raw patterns
+      # @return [Array<String>] the cleaned, lowercased patterns
+      def normalize_patterns(patterns)
+        Array(patterns).filter_map do |pattern|
+          cleaned = pattern.to_s.strip.downcase
+          cleaned unless cleaned.empty?
+        end
+      end
+
+      # Reduce a sender address to its tag-stripped, lowercased routing key.
+      #
+      # Delegates to +Gateway::Mail::Address+ so subaddressing and RFC 5322 forms line up with the
+      # routing used elsewhere; on a malformed address, falls back to a raw downcased comparison so a
+      # deny rule can still match obviously-bad input.
+      #
+      # @param address [String] the raw sender address
+      # @return [String] the comparison key
+      def routing_key_for(address)
+        Mail::Address.parse(address).routing_key
+      rescue ArgumentError
+        address.to_s.strip.downcase
+      end
+
+      # Test one pattern against one routing key, expanding a single +*+ wildcard.
+      #
+      # @param pattern [String] the normalized rule (may contain +*+)
+      # @param key [String] the normalized sender routing key
+      # @return [Boolean] true when the pattern matches the key
+      def matches?(pattern:, key:)
+        regex = Regexp.new("\\A#{Regexp.escape(pattern).gsub('\\*', '.*')}\\z")
+        regex.match?(key)
+      end
+    end
+  end
+end

data/lib/protege/gateway/attachment_policy.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Protege
+  module Gateway
+    # Immutable attachment limits + the policy that enforces them. A Gateway value type consulted at the
+    # mail edges — built through the +Gateway.build_attachment_policy+ factory and assigned as
+    # +config.attachment_policy+:
+    #
+    #   config.attachment_policy = Protege::Gateway.build_attachment_policy(max_bytes: 5.megabytes)
+    #
+    # A +Data+ value with the engine's default limits, consulted at the edges: the inbound mailbox
+    # bounces a violation, and the +send_email+ tool refuses one. +enabled+ is the master switch — when
+    # false, *any* attachment is rejected (inbound mail with attachments bounces; the agent can't attach
+    # files), while plain mail is unaffected. When enabled, limits are checked in a fixed order — count,
+    # then per-attachment size, then total size — and the first breach wins, so +#violation+ returns a
+    # single human-readable reason (or +nil+ when the set is acceptable).
+    AttachmentPolicy = Data.define(:enabled, :max_bytes, :max_count, :max_total_bytes) do
+      # @param enabled [Boolean] whether attachments are accepted at all (default true)
+      # @param max_count [Integer] maximum attachments per message (default 10)
+      # @param max_bytes [Integer] maximum bytes per attachment (default 10 MB)
+      # @param max_total_bytes [Integer] maximum combined bytes (default 25 MB)
+      def initialize(
+        enabled: true,
+        max_count: 10,
+        max_bytes: 10 * 1024 * 1024,
+        max_total_bytes: 25 * 1024 * 1024
+      )
+        super
+      end
+
+      # Report whether the given attachment sizes are acceptable.
+      #
+      # @param byte_sizes [Array<Integer>] each attachment's size in bytes
+      # @return [Boolean] true when the set is acceptable
+      def permits?(byte_sizes:)
+        violation(byte_sizes:).nil?
+      end
+
+      # Return the first reason the set is rejected, or +nil+ when acceptable. A message with no
+      # attachments is always acceptable, even when attachments are disabled.
+      #
+      # @param byte_sizes [Array<Integer>] each attachment's size in bytes
+      # @return [String, nil] the rejection reason, or nil
+      def violation(byte_sizes:)
+        sizes = Array(byte_sizes)
+
+        return nil if sizes.empty?
+
+        %i[
+          attachments_disabled?
+          too_many_attachments?
+          any_attachment_too_large?
+          total_size_exceeded?
+        ].each do |validator|
+          if (reason = send(validator, sizes))
+            return reason
+          end
+        end
+
+        nil
+      end
+
+      private
+
+      # Render a byte count as a rounded megabytes label for limit messages.
+      #
+      # @param bytes [Integer] the byte count
+      # @return [String] e.g. +"10 MB"+
+      def megabytes(bytes)
+        "#{(bytes / (1024.0 * 1024)).round} MB"
+      end
+
+      # Determines if attachments are enabled at all.
+      #
+      # @param _sizes [Array<Integer>] each attachment's size in bytes (ignored)
+      # @return [String, nil] a rejection reason when disabled, or +nil+ when enabled
+      # @param [Object] _sizes
+      def attachments_disabled?(_sizes)
+        return false if enabled
+
+        'attachments are not accepted'
+      end
+
+      # Determines if there are too many attachments, based on the +max_count+ limit.
+      #
+      # @param sizes [Array<Integer>] each attachment's size in bytes
+      # @return [String, nil] a rejection reason when too many, or +nil+ when acceptable
+      def too_many_attachments?(sizes)
+        return false if sizes.size <= max_count
+
+        "too many attachments (max #{max_count})"
+      end
+
+      # Determines if any attachment exceeds the +max_bytes+ limit.
+      #
+      # @param sizes [Array<Integer>] each attachment's size in bytes
+      # @return [String, nil] a rejection reason when any attachment is too large, or +nil+ when acceptable
+      def any_attachment_too_large?(sizes)
+        return false if sizes.none? { _1 > max_bytes }
+
+        "an attachment exceeds the #{megabytes(max_bytes)} limit"
+      end
+
+      # Determines if the total of all attachments exceeds the +max_total_bytes+ limit.
+      #
+      # @param sizes [Array<Integer>] each attachment's size in bytes
+      # @return [String, nil] a rejection reason when the total size is exceeded, or +nil+ when acceptable
+      def total_size_exceeded?(sizes)
+        return false if sizes.sum <= max_total_bytes
+
+        "attachments exceed the #{megabytes(max_total_bytes)} total limit"
+      end
+    end
+  end
+end

data/lib/protege/gateway/mail/address.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'mail'
+
+module Protege
+  module Gateway
+    # Namespace for email-specific value objects — addresses, Message-IDs,
+    # and References chains — used when parsing inbound mail and building
+    # threaded replies. Pure lexical helpers with no transport concerns.
+    module Mail
+      # Value object representing an email address with optional plus-tag
+      # and optional display name.
+      #
+      # Instances are frozen. Local part, tag, and domain are lowercased.
+      # Construct via +.parse+, which delegates lexical parsing to
+      # +::Mail::Address+ (handling RFC 5322 oddities like quoted display
+      # names and comments) and then layers plus-tag splitting and the
+      # routing-key concern on top.
+      #
+      # Raises +ArgumentError+ when input is nil, blank, or has no +@+
+      # separator. Display name is excluded from equality — two addresses
+      # with the same +local+, +tag+, and +domain+ are equal regardless of
+      # the surrounding display name.
+      class Address
+        # Bare mailbox name with any plus-tag stripped, lowercased.
+        attr_reader :local
+
+        # Plus-tag suffix, or nil if no +tag was present in the source.
+        attr_reader :tag
+
+        # Domain part of the address, lowercased.
+        attr_reader :domain
+
+        # Display name from a +"Name" <addr>+ form, or nil if absent.
+        attr_reader :display_name
+
+        class << self
+          # Parse a raw address string into a normalized +Address+.
+          #
+          # Delegates the lexical parse to +::Mail::Address+ so quoted display names, comments, and
+          # other RFC 5322 syntax are handled, then splits any plus-tag off the local part and
+          # lowercases the local and domain.
+          #
+          # @param value [String] the raw address (optionally with display name and plus-tag).
+          # @return [Address] the normalized, frozen address.
+          # @raise [ArgumentError] when +value+ is nil/blank or has no +@+-separated mailbox.
+          def parse(value)
+            raise ArgumentError, 'address cannot be nil or blank' if value.nil? || value.to_s.strip.empty?
+
+            parsed       = validate_mailbox(::Mail::Address.new(value.to_s.strip), value)
+            local, tag   = split_plus_tag(parsed.local.downcase)
+            domain       = parsed.domain.downcase
+            display_name = parsed.display_name
+
+            new(local:, tag:, domain:, display_name:)
+          end
+
+          private
+
+          # Ensure a parsed mailbox has both a local part and a domain.
+          #
+          # @param parsed [::Mail::Address] the result of the lexical parse.
+          # @param original [String] the original input, used in the error message.
+          # @return [::Mail::Address] +parsed+ unchanged when valid.
+          # @raise [ArgumentError] when the local part or domain is missing.
+          def validate_mailbox(parsed, original)
+            return parsed unless parsed.local.nil? ||
+                                 parsed.local.empty? ||
+                                 parsed.domain.nil? ||
+                                 parsed.domain.empty?
+
+            raise ArgumentError, "address missing '@': #{original.inspect}"
+          end
+
+          # Split a local part into its bare name and optional plus-tag.
+          #
+          # @param local_with_tag [String] the lowercased local part, possibly containing +'+'+.
+          # @return [Array(String, String), Array(String, nil)] the bare local and tag, or
+          #   +[local, nil]+ when no plus-tag is present.
+          def split_plus_tag(local_with_tag)
+            plus_index = local_with_tag.index('+')
+            return [local_with_tag, nil] if plus_index.nil?
+
+            [
+              local_with_tag[0...plus_index],
+              local_with_tag[(plus_index + 1)..]
+            ]
+          end
+        end
+
+        # Wrap pre-parsed address parts and freeze. Prefer +.parse+.
+        #
+        # Blank display names are coerced to +nil+ so equality and rendering ignore them.
+        #
+        # @param local [String] the bare mailbox name, lowercased.
+        # @param domain [String] the domain, lowercased.
+        # @param tag [String, nil] the plus-tag, or +nil+.
+        # @param display_name [String, nil] the display name, or +nil+/blank to omit.
+        def initialize(local:, domain:, tag: nil, display_name: nil)
+          @local        = local
+          @tag          = tag
+          @domain       = domain
+          @display_name = display_name.nil? || display_name.to_s.strip.empty? ? nil : display_name
+
+          freeze
+        end
+
+        # Return the tag-stripped +local@domain+ form used for routing.
+        #
+        # @return [String] the routing key with no plus-tag.
+        def routing_key
+          "#{@local}@#{@domain}"
+        end
+
+        # Return the canonical mailbox form, including the plus-tag when present.
+        #
+        # The display name is never included.
+        #
+        # @return [String] +local+tag@domain+ or +local@domain+.
+        def to_s
+          @tag ? "#{@local}+#{@tag}@#{@domain}" : "#{@local}@#{@domain}"
+        end
+
+        # Compare for equality by local, tag, and domain, ignoring display name.
+        #
+        # @param other [Object] the value to compare against.
+        # @return [Boolean] +true+ when +other+ is an +Address+ with matching parts.
+        def ==(other)
+          other.is_a?(Address) &&
+            other.local == @local &&
+            other.tag == @tag &&
+            other.domain == @domain
+        end
+        alias eql? ==
+
+        # Hash by local, tag, and domain so equal addresses hash alike.
+        #
+        # @return [Integer] the hash code.
+        def hash
+          [@local, @tag, @domain].hash
+        end
+      end
+    end
+  end
+end

data/lib/protege/gateway/mail/attachment.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Protege
+  module Gateway
+    module Mail
+      # Value object for a file as a mail attachment — the typed payload +Outbound+ turns into a MIME
+      # part. It is the one shape the send path speaks: a filename, a content type, and the raw bytes on
+      # the wire. Both a reattached stored file (+Protege::StoredFile#to_mail_attachment+) and any
+      # freshly produced bytes become one of these, so the payload is defined in a single place rather
+      # than passed around as an anonymous Hash (mirroring how +::Mail+ is confined to +Outbound+).
+      #
+      # These bytes are for *transport* only; the file's durable identity remains its blob, which the
+      # outbound message attaches by reference on persistence.
+      Attachment = Data.define(:filename, :content_type, :bytes)
+    end
+  end
+end

data/lib/protege/gateway/mail/message_id.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Protege
+  module Gateway
+    module Mail
+      # Value object representing an RFC 5322 Message-ID.
+      #
+      # Instances are frozen on construction; equality is based on the
+      # normalized string value. Construct via the factory methods —
+      # +.parse+, +.synthetic+, or +.ensure+ — rather than +.new+.
+      class MessageId
+        # Matches a leading or trailing angle bracket, used to strip stray brackets before re-wrapping.
+        EDGE_BRACKETS = /\A<|>\z/
+        private_constant :EDGE_BRACKETS
+
+        class << self
+          # Parse a raw value into a normalized, angle-bracketed +MessageId+.
+          #
+          # Trims surrounding whitespace and preserves case. Already-bracketed values pass through;
+          # half-bracketed values lose the stray bracket before being re-wrapped.
+          #
+          # @param value [String] the raw message-id, with or without brackets.
+          # @return [MessageId] the normalized message id.
+          def parse(value)
+            new(normalize(value))
+          end
+
+          # Build a unique synthetic +MessageId+ for inputs that lack one.
+          #
+          # The +domain+ should be the real sending domain for outbound mail, so the Message-ID is
+          # well-formed and recipients (e.g. Gmail) trust it and thread replies. It defaults to
+          # +protege.local+ only for the inbound/console fallback case, where the id is internal and
+          # never travels back out.
+          #
+          # @param domain [String] the domain for the id's right-hand side.
+          # @return [MessageId] a fresh +<synthetic.UUID@domain>+ id.
+          def synthetic(domain: 'protege.local')
+            new("<synthetic.#{SecureRandom.uuid}@#{domain}>")
+          end
+
+          # Parse +value+, or fall back to a synthetic id when it is missing.
+          #
+          # @param value [String, nil] the raw message-id, possibly nil or blank.
+          # @return [MessageId] the parsed id, or a synthetic one when +value+ is nil/blank.
+          def ensure(value)
+            return synthetic if value.nil? || value.to_s.strip.empty?
+
+            parse(value)
+          end
+
+          private
+
+          # Normalize a raw value to a trimmed, angle-bracketed string.
+          #
+          # @param value [String] the raw message-id.
+          # @return [String] the value wrapped in a single pair of angle brackets.
+          def normalize(value)
+            trimmed = value.to_s.strip
+            return trimmed if trimmed.start_with?('<') && trimmed.end_with?('>')
+
+            "<#{trimmed.gsub(EDGE_BRACKETS, '')}>"
+          end
+        end
+
+        # Normalized message-id string (always angle-bracketed).
+        attr_reader :value
+
+        # Wrap a pre-normalized value and freeze. Prefer the factory methods.
+        #
+        # @param value [String] an already-normalized, angle-bracketed message-id.
+        def initialize(value)
+          @value = value
+          freeze
+        end
+
+        # Compare by normalized value.
+        #
+        # @param other [Object] the value to compare against.
+        # @return [Boolean] +true+ when +other+ is a +MessageId+ with the same value.
+        def ==(other)
+          other.is_a?(MessageId) && @value == other.value
+        end
+
+        alias eql? ==
+
+        # Hash by normalized value so a +MessageId+ works as a Hash key.
+        #
+        # @return [Integer] the hash code.
+        def hash
+          @value.hash
+        end
+
+        # Return the normalized string value.
+        #
+        # @return [String] the angle-bracketed message-id.
+        def to_s
+          @value
+        end
+      end
+    end
+  end
+end