protege 0.1.0.alpha.1

data/app/models/concerns/protege/tool_scoped.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Protege
+  # Per-persona tool scoping — mixed into +Persona+ to bound which tools an agent may use.
+  #
+  # A persona's effective tools are the code-declared *grant* (the ceiling, set by the {ClassMethods#tools}
+  # macro) minus the operator's +disabled_tool_ids+ override, and never wider than the grant. Two layers,
+  # deliberately different in reach:
+  #
+  # * The grant lives on a +class_attribute+ so it survives Active Record's schema-loading reloads (the
+  #   same reason +Persona._display_name+ is one). Unlike the resolver chains — per-subclass +@ivar+s that
+  #   never inherit — the grant *inherits* down the STI tree, so a base persona narrows a whole family's
+  #   ceiling unless a subclass declares its own. A nil grant means "every registered tool", so an
+  #   unconfigured persona keeps the full catalogue (the pre-scoping behaviour).
+  # * +disabled_tool_ids+ is a dashboard-editable JSON array on the row (text column; SQLite has no native
+  #   JSON type), normalised to a clean string array so it is never nil. It can only *subtract* from the
+  #   grant, never add to it.
+  #
+  # {#available_tools} resolves both layers against the live registry, so a stale grant or disabled id —
+  # naming a tool since deleted from the code — is simply skipped rather than conjuring or breaking a tool.
+  module ToolScoped
+    extend ActiveSupport::Concern
+
+    included do
+      serialize :disabled_tool_ids, coder: JSON
+      before_validation :normalize_disabled_tool_ids
+
+      # Backing store for the code-declared grant (tool ids, or nil for "all tools"). Inherits down STI.
+      class_attribute :_tool_grant, instance_accessor: false
+    end
+
+    # Class-level DSL for declaring the grant.
+    class_methods do
+      # Declare the tools this persona subclass may use — the code-side ceiling of its tool scope.
+      #
+      # A DSL macro (positional by convention, like +message_resolver+): given tool ids it records them as
+      # symbols. Omitting it leaves the grant nil ("every registered tool"). The operator can only narrow
+      # this grant at runtime via +disabled_tool_ids+, never widen it.
+      #
+      # @param ids [Array<Symbol, String>] the tool ids the persona is allowed to use
+      # @return [Array<Symbol>] the recorded grant
+      def tools(*ids)
+        self._tool_grant = ids.map(&:to_sym)
+      end
+
+      # Return this subclass's declared tool grant, or nil when none was declared ("all tools").
+      #
+      # @return [Array<Symbol>, nil] the granted tool ids, or nil for the full catalogue
+      def tool_grant
+        _tool_grant
+      end
+    end
+
+    # Return the tool classes this persona may currently use — its effective, scoped catalogue.
+    #
+    # Computed as one filter over the live registry (+ToolMixin.registered+): drop anything the operator
+    # has switched off in +disabled_tool_ids+, then keep only what the subclass's grant permits (or
+    # everything, when the grant is nil). Iterating the registry rather than the grant means a grant id
+    # with no matching registered tool is simply skipped — a stale scope can never conjure or break a tool.
+    #
+    # @return [Array<Class>] the tool classes offered to the model for this persona
+    def available_tools
+      disabled = disabled_tool_ids.map(&:to_sym)
+      grant    = self.class.tool_grant
+
+      ToolMixin.registered
+               .reject { |tool| disabled.include?(tool.id) }
+               .select { |tool| grant.nil? || grant.include?(tool.id) }
+    end
+
+    # The ids of this persona's effective tools — a convenience over {#available_tools} for UI and tests.
+    #
+    # @return [Array<Symbol>] the effective tool ids
+    def available_tool_ids
+      available_tools.map(&:id)
+    end
+
+    private
+
+    # Coerce +disabled_tool_ids+ to a deduped, blank-stripped array of strings so the JSON column stays
+    # clean regardless of how it was assigned (symbols, blanks, nils, duplicates) and is never nil.
+    #
+    # @return [void]
+    def normalize_disabled_tool_ids
+      self.disabled_tool_ids = Array(disabled_tool_ids).map(&:to_s).reject(&:blank?).uniq
+    end
+  end
+end

data/app/models/protege/access_rule.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Protege
+  # One runtime allow/deny rule for a single persona — the dashboard-editable layer of the inbound
+  # access-control guardrail. Each record carries a +kind+ (+allow+/+deny+) and an address +pattern+
+  # (an exact address or a +*+ wildcard such as +*@company.co+); together a persona's rules fold into
+  # a +Gateway::AccessPolicy+ via {.policy_for}.
+  #
+  # This is the *narrowing* layer: +AccessControl+ intersects it with the committed global policy
+  # (+Protege.configuration.inbound_access+), so a persona's rules can only further restrict who may
+  # reach that agent — never widen past the org-wide ceiling. A persona with no rules imposes no
+  # constraint of its own.
+  class AccessRule < ApplicationRecord
+    # ── Associations ────────────────────────────────────────────────────────
+
+    belongs_to :persona, class_name: 'Protege::Persona'
+
+    # ── Attributes ──────────────────────────────────────────────────────────
+
+    # Whether this rule admits (+allow+) or blocks (+deny+) matching senders.
+    enum :kind, { allow: 'allow', deny: 'deny' }
+
+    # ── Validations ─────────────────────────────────────────────────────────
+
+    # A rule with no pattern matches nothing and is meaningless; the address pattern is required.
+    validates :pattern, presence: true
+
+    # ── Class methods ───────────────────────────────────────────────────────
+
+    class << self
+      # Fold one persona's rules into a single +Gateway::AccessPolicy+.
+      #
+      # Groups the persona's +allow+/+deny+ patterns into the policy's lists; the policy then derives
+      # its own default (an allow-list implies default-deny). A persona with no rules yields a bare
+      # +Gateway::AccessPolicy+, which permits everyone and so drops out of the +AccessControl+
+      # intersection.
+      #
+      # @param persona [Protege::Persona] the persona whose rules to fold
+      # @return [Protege::Gateway::AccessPolicy] the persona's runtime access policy
+      def policy_for(persona)
+        grouped = where(persona:).group_by(&:kind)
+
+        Gateway.build_access_policy(
+          allow: Array(grouped['allow']).map(&:pattern),
+          deny:  Array(grouped['deny']).map(&:pattern)
+        )
+      end
+    end
+  end
+end

data/app/models/protege/application_record.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Protege
+  # Abstract base class for every Active Record model in the Protege engine.
+  #
+  # Every persisted model — +Persona+, +Message+, +EmailThread+, +EmailDomain+ — inherits
+  # from this class rather than +ActiveRecord::Base+ directly, mirroring the convention a host
+  # Rails application uses for its own +ApplicationRecord+. Keeping a dedicated base class gives
+  # the engine a single seam for shared concerns (connection handling, common scopes, callbacks)
+  # without leaking configuration into the host application's models.
+  #
+  # The class is marked abstract so Active Record never expects a +protege_application_records+
+  # table to exist.
+  class ApplicationRecord < ActiveRecord::Base
+    # Declare this class abstract so Active Record treats it as a base only, never a table.
+    self.abstract_class = true
+  end
+end

data/app/models/protege/current.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Protege
+  # Thread-local, per-run state for a single Protege processing pass.
+  #
+  # Subclasses +ActiveSupport::CurrentAttributes+, so every attribute declared here is reset
+  # automatically at the start of each web request and each Active Job execution. Values must
+  # therefore be set explicitly at the origin of each run and are never carried implicitly from
+  # one run to the next.
+  #
+  # Within the LOGI pipeline this is the carrier for the correlation ID that ties a single inbound
+  # email to every downstream event. +AgentMailbox#process+ sets +correlation_id+ from the inbound
+  # email's RFC 2822 Message-ID; +InferenceJob#perform+ and +ConsoleInferenceJob#perform+ restore
+  # it at the top of the job. This lets the trace token flow from Gateway ingress through Inference
+  # without being threaded through every method signature.
+  #
+  # @example Set the correlation ID at the ingress boundary
+  #   Protege::Current.correlation_id = mail.message_id
+  class Current < ActiveSupport::CurrentAttributes
+    # Trace token shared by all events emitted during one processing run; the inbound Message-ID.
+    attribute :correlation_id
+  end
+end

data/app/models/protege/email_domain.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'base64'
+
+module Protege
+  # A mail domain the Protege engine is configured to receive email for.
+  #
+  # Each domain owns a 2048-bit RSA keypair, generated automatically on create and stored as PEM in
+  # +dkim_private_key_pem+; the public half is derived on demand for the DKIM DNS record. The model
+  # exists to drive the domain show page, which surfaces the four DNS records an operator must
+  # publish before the domain can receive and authenticate mail: MX (inbound routing), SPF
+  # (envelope sender authorisation), DKIM (signing key), and DMARC (alignment policy). Rotating the
+  # keypair therefore requires republishing the DKIM TXT record.
+  class EmailDomain < ApplicationRecord
+    self.table_name = 'protege_email_domains'
+
+    # ── Concerns ──────────────────────────────────────────────────────────────
+
+    # Keep the Domains sidebar live (append/replace/remove).
+    include BroadcastableEmailDomain
+
+    # ── Validations ─────────────────────────────────────────────────────────
+
+    validates :domain, presence: true, uniqueness: true
+
+    # ── Scopes ──────────────────────────────────────────────────────────────
+
+    # Domains ordered by name, as shown in UI selectors.
+    default_scope { order(:domain) }
+
+    # ── Callbacks ───────────────────────────────────────────────────────────
+
+    # Generate the DKIM keypair before the record is first validated.
+    before_validation :generate_dkim_keypair, on: :create
+
+    # Re-provision the self-hosted MTA after any change so its signing keys/tables track the DB. The
+    # push happens off the request via +MailProvisioningJob+; a no-op in provider mode.
+    after_commit :provision_mail_server, on: %i[create update destroy]
+
+    # ── Class methods ─────────────────────────────────────────────────────────
+
+    class << self
+      # Report whether Protege receives mail for the given address's domain — i.e. whether it belongs
+      # to a registered +EmailDomain+. Drives the Action Mailbox routing predicate (+Gateway.claims?+)
+      # so the engine claims only its own inbound mail; until a domain is added, nothing routes.
+      # Parsing is delegated to +Gateway::Mail::Address+; blank or malformed input is not ours.
+      #
+      # @param address [String, nil] a recipient address from an inbound email
+      # @return [Boolean] true when the address's domain is one Protege receives for
+      def receives?(address)
+        exists?(domain: Gateway::Mail::Address.parse(address).domain)
+      rescue ArgumentError
+        false
+      end
+    end
+
+    # ── DNS record helpers ───────────────────────────────────────────────────
+
+    # Return the DNS hostname for the DKIM TXT record: +<selector>._domainkey.<domain>+.
+    #
+    # @return [String] the fully qualified DKIM record name
+    def dkim_dns_name
+      "#{dkim_selector}._domainkey.#{domain}"
+    end
+
+    # Return the Base64-encoded DER public key for the DKIM TXT record value.
+    #
+    # Derives the public key from the stored private PEM each call, so it always matches the
+    # current keypair.
+    #
+    # @return [String] the strict-Base64-encoded public key
+    def dkim_public_key_base64
+      key = OpenSSL::PKey::RSA.new(dkim_private_key_pem)
+      Base64.strict_encode64(key.public_key.to_der)
+    end
+
+    # Return the MX record value pointing inbound mail at this server.
+    #
+    # @return [String] the MX record value, with priority 10
+    def mx_record
+      "10 #{domain}."
+    end
+
+    # Return the SPF TXT record value for the domain apex.
+    #
+    # @return [String] an SPF policy authorising the domain's MX hosts
+    def spf_txt_record
+      'v=spf1 mx ~all'
+    end
+
+    # Return the DKIM TXT record value published at {#dkim_dns_name}.
+    #
+    # @return [String] the DKIM record carrying the RSA public key
+    def dkim_txt_record
+      "v=DKIM1; k=rsa; p=#{dkim_public_key_base64}"
+    end
+
+    # Return the DMARC TXT record value published at +_dmarc.<domain>+.
+    #
+    # @return [String] a strict-alignment, reject-policy DMARC record
+    def dmarc_txt_record
+      "v=DMARC1; p=reject; adkim=s; aspf=s; rua=mailto:dmarc@#{domain}"
+    end
+
+    # ── MTA provisioning ──────────────────────────────────────────────────────
+
+    # The minimal signing material the self-hosted MTA needs to sign this domain's outbound mail — the
+    # domain, its DKIM selector, and the private key. One entry in +Gateway.mail_provisioning_manifest+,
+    # which the app pushes to the mail accessory's control listener whenever a domain changes.
+    #
+    # @return [Hash] the domain's provisioning entry
+    def to_provisioning
+      { domain:, selector: dkim_selector, private_key_pem: dkim_private_key_pem }
+    end
+
+    private
+
+    # Generate and store a fresh RSA-2048 keypair on create.
+    #
+    # Idempotent: assigns the PEM only when one is not already present, so re-running validation
+    # never overwrites an existing key.
+    #
+    # @return [void]
+    def generate_dkim_keypair
+      self.dkim_private_key_pem ||= OpenSSL::PKey::RSA.generate(2048).to_pem
+    end
+
+    # Enqueue a push of the whole domain manifest to the self-hosted MTA accessory.
+    #
+    # @return [void]
+    def provision_mail_server
+      MailProvisioningJob.perform_later
+    end
+  end
+end

data/app/models/protege/email_thread.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Protege
+  # Groups every +Message+ belonging to a single email conversation.
+  #
+  # A thread is identified by its canonical +thread_id+: the RFC 2822 Message-ID of the conversation
+  # root. For a reply that is the first entry of the References chain (falling back to In-Reply-To);
+  # for a brand-new conversation it is the message's own Message-ID. Threads belong to one +Persona+
+  # and carry denormalised counters (+message_count+, +last_message_at+) that +Message+ keeps fresh
+  # so the inbox can sort and display without aggregating on every render.
+  class EmailThread < ApplicationRecord
+    # ── Concerns ────────────────────────────────────────────────────────────
+
+    include BroadcastableThread
+
+    # ── Associations ────────────────────────────────────────────────────────
+
+    belongs_to :persona, class_name: 'Protege::Persona'
+
+    # Destroying a thread removes its messages; inverse lets Message keep counters in sync. Each message
+    # in turn destroys its own recorded tool uses (see +Message+), so a thread's tool history is torn
+    # down with it.
+    has_many :messages, dependent: :destroy, inverse_of: :email_thread
+
+    # ── Scopes ──────────────────────────────────────────────────────────────
+
+    # Eager-load persona and messages, most-recently-active first — the inbox listing query.
+    scope :for_inbox, -> { includes(:persona, :messages).order(last_message_at: :desc) }
+
+    # ── Validations ─────────────────────────────────────────────────────────
+
+    with_options presence: true do
+      # The canonical Message-ID must be unique so each conversation maps to one thread.
+      validates :thread_id, uniqueness: true
+      validates :persona
+    end
+
+    # ── Instance methods ─────────────────────────────────────────────────────
+
+    # Return the most recently sent message in the thread.
+    #
+    # @return [Protege::Message, nil] the latest message, or nil for an empty thread
+    def latest_message
+      messages.order(:sent_at).last
+    end
+
+    # ── Class methods ───────────────────────────────────────────────────────
+
+    class << self
+      # Derive the canonical RFC 2822 thread-root ID from a mail object.
+      #
+      # Checks the References chain first (its head is the conversation root), then In-Reply-To,
+      # then falls back to the message's own Message-ID for a new conversation. The result is
+      # normalized through +Gateway::Mail+ so every thread id is stored in canonical angle-bracketed
+      # form regardless of how the raw header was punctuated.
+      #
+      # @param mail [Mail::Message] the email to inspect
+      # @return [String] the canonical, angle-bracketed thread identifier
+      def thread_id_for(mail)
+        Gateway.reference_ids(mail.references).first ||
+          Gateway.canonical_message_id(mail.in_reply_to.presence || mail.message_id)
+      end
+
+      # Find or create the thread for the given mail and persona.
+      #
+      # On creation, seeds the persona, subject, and last-activity timestamp from the mail.
+      #
+      # @param mail [Mail::Message] the email being threaded
+      # @param persona [Protege::Persona] the persona that owns the conversation
+      # @return [Protege::EmailThread] the existing or newly created thread
+      # @raise [ActiveRecord::RecordInvalid] when a new thread fails validation
+      def find_or_create_for(mail:, persona:)
+        find_or_create_by!(thread_id: thread_id_for(mail)) do |t|
+          t.persona         = persona
+          t.subject         = mail.subject.to_s
+          t.last_message_at = Time.current
+        end
+      end
+    end
+  end
+end